Consuming the SharePoint 2013 REST API from PowerShell

Introduction

SharePoint 2013 introduces a Representational State Transfer (REST) service that is comparable to the  SharePoint CSOM and in addition to CSOM, REST API opens up a huge capabilities, in particular for administering and automating SharePoint Online when used with PowerShell.

Sending  REST requests to a SharePoint Online 

In the previous post we’ve already covered how to perform read operations by sending HTTPS requests to SharePoint RESTful web services. This time we are going to extend PowerShell script  in order to support all the CRUD operations.

The Invoke-RestSPO function sends  HTTPS requests to SharePoint REST web services that returns richly structured data (JSON)

Request Digests

Since SharePoint requires the user to include a request digest value with each create, update and delete operation, an additional request is invoked using Get-SPOContextInfo function to request Context Info entity that contains request digest value.

 ETag

In order to avoid an additional request, “*” eTag value is used to match any eTag value resulting in the operation being performed regardless of the actual value.

Lists manipulation using REST API in PowerShell

This section contains sample code for all of the CRUD operations.

References

 

List Items manipulation via REST API in SharePoint 2010

Introduction

Apart from CSOM API,  REST API introduces another approach to access SharePoint list data from platforms on which the CSOM may be unavailable. The SharePoint REST interface is based on the REST-based Open Data protocol (OData) which  is a platform-independent open standard.

Examples

This section contains sample code for all of the CRUD operations.

Create

In order to  perform a Create operation via REST, you must perform the following actions:

  • Create an HTTP request using the POST verb.
  • Use the service URL of the list to which you want to add an entity as the target for the POST.
  • Set the content type to application/json.
  • Serialize the JSON objects that represent your new list items as a string, and add this value to the request body.

The following code snippet demonstrates how to perform a Create operation against a SharePoint list.

Read

In order to  perform a Read operation via REST, you must perform the following actions:

  • Create an HTTP request using the GET verb.
  • Use the service URL of the list item to which you want to add an entity as the target for the GET.
  • Set the content type to application/json.

The code sample demonstrates of how to retrieve an item based on its ID:

Update

To  update an existing entity, you must perform the following actions:

  • Create an HTTP request using the POST verb.
  • Add an X-HTTP-Method header with a value of MERGE.
  • Use the service URL of the list item you want to update as the target for the POST
  • Add an If-Match header with a value of the entity’s original ETag.

In contrast to reading list item  to update an item you will need to pass the eTag value, which could be obtained during item read.

About eTags

When updating or deleting items within SharePoint lists via REST you must specify the Entity Tag (eTag) value that was returned with the item during the initial query. This enables SharePoint to determine if the item has changed since it was requested. Alternatively you can tell SharePoint to perform the operation regardless by specifying * as the eTag value. For example:

  1. “If-Match”: item.__metadata.etag can be used to specify the actual eTag value (‘item’ is the object returned from SharePoint containing the list item in JSON format).
  2. “If-Match”: “*” can be used to match any eTag value resulting in the operation being performed regardless of the actual value.

They form part of the Ajax call for updating an item. eTags are part of the HTTP Protocol V1.1, more information on the topic can be found here.

Delete

To  delete an  entity, you must perform the following actions:

  • Create an HTTP request using the POST verb.
  • Add an X-HTTP-Method header with a value of DELETE.
  • Use the service URL of the list item you want to update as the target for the POST
  • Add an If-Match header with a value of the entity’s original ETag.

The Delete operation is similar to Update operation,  the code below demonstrates how to perform a Delete operation:

References

Introduction to Client Forms Validation in SharePoint 2013

Client side event handlers in SharePoint

In addition to server side Event Model,  SharePoint also provides client side  event handling capabilities when working with List Forms.

Let’s see briefly how it works. In List Forms pages Save button click handler triggers PreSaveItem function , PreSaveItem function is declared in forms.js:

PreSaveAction function from another hand, is a user defined function that allows to override standard behavior for a Save button handler, so in terms of server side event model it is a binding mechanism.

I find this mechanism  pretty convenient for implementing custom client side validation in List Forms,  the following example demonstrates how to implement client side validation for Email field in Contacts list:

EmailValidate

Client forms validation in SharePoint 2013

In SharePoint 2013 as part of  Client-Side Rendering (CSR), there is SPClientForms.ClientValidation  namespace (clientforms.js) that contains  types and objects for performing  client side validation in List Forms. For example,

SPClientForms.ClientValidation.RequiredValidator object is intended for evaluating the value of an field control to ensure that the user enters a value (it  is invoked for a fields when SPField.Required property is set to True):

Below is provided a complete example that demonstrates how to implement  client-side validation for Email field in Contacts list:

Key points:

  • CustomClientValidation.EmailValidator object implements a custom validation  for Email field
  • since Email field is a standard Text Field,  the rendering of field control is reused, only custom validator is registered for a field (see function EmailField_Edit for a details)

Working with the SharePoint Online REST service via PowerShell

Since SharePoint 2013 introduces a Representational State Transfer (REST) service that is comparable to the existing SharePoint client object models, it opens up a huge capabilities, in particular for administering and automating SharePoint Online when used with PowerShell.

My first idea was to utilize  Invoke-RestMethod cmdlet, which was introduced in Windows PowerShell 3.0.  Invoke-RestMethod cmdlet contains Credential parameter which could  accept basic, digest, NTLM, and Kerberos authentication.

SharePoint Client Component SDK comes with  a SharePointOnlineCredentials class  which represents an object that provides credentials to access SharePoint Online resources. But unfortunately SharePoint Online credentials could not be passed in Invoke-RestMethod cmdlet, since claims based authentication is not supported by this cmdlet.

Below is demonstrated a simplified PowerShell script  that to some extent mimics Invoke-RestMethod cmdlet. This script is intended for sending HTTPS request to a SharePoint Online REST service:

Examples

References

Working with Discussions List via SharePoint Client Object Model

Overview

In this post  will be demonstrated how to perform a common CRUD operations when working with Discussions List via  Client Object Model (JavaScript CSOM) in SharePoint 2010/2013.

Create a Discussion

So, let’s get started with creating a Discussion item. SP.Utilities.Utility.createNewDiscussion method is used for creating a discussion item:

Load all Discussions

Since Discussion Content Type derives from Folder Content Type  we could utilize SP.CamlQuery.createAllFoldersQuery method to construct a query to retrieve all the discussions:

Create a Message

The SP.Utilities.Utility.createNewDiscussionReply method is used to create a Message item (add reply to a discussion item):

Load all Messages

Since message items  are contained within discussion container (Folder) , to identify messages by discussion we will use SPBuiltInFieldId.ParentFolderId field in CAML query:

Import Discussion List

And finally in order to see how to work with Discussions List in action,  let’s discuss one more example.  Suppose we need to import Discussions List content from an external source, let’s say from Stack Exchange. To access Stack Exchange content (Questions and Answers in our case) we will utilize Stack Exchange API:

How to populate a SharePoint List via CSOM

Overview

Populating a SharePoint List with data is  required for different purposes quite often. In this article I am going to demonstrate how to populate Contacts list with a fake data using CSOM.

Provision column to a List via SharePoint CSOM

We will utilize Contacts List for demonstration purposes. But before we  proceed, let’s add a Geolocation field to a list.

Since the Geolocation column is not available by default in SharePoint lists, it’s common practice to provision this field to a list programmatically. The code below demonstrates  how to add the Geolocation field  by using the SharePoint client object model:

Generate list data

For populating Contacts list we will utilize Faker.js JavaScript library that is intended for generating massive amounts of fake data, below is provided the complete code:

Results

After running the script the Contacts list will be populated with a fake data as demonstrated below.

Contacts default view

Contacts

Contacts map view

ContactsMap

References

Some tips and tricks of using SharePoint Client Object Model in PowerShell. Part 1

Overview

When it comes to using SharePoint 2010 Client Object Model (CSOM) we need to be ready for certain kind of  limitations  in PowerShell. First of all, it concerns the usage of Generics Methods, for the example ClientRuntimeContext.Load<T> method:

An attempt to call the method ClientRuntimeContext.Load<T> directly will result in the following error

PSGenericMethods

This is a limitation of PowerShell  (V1, V2 and V3) AFAIK.

There are several options how to bypass this limitation but in this post I would like to concentrate only on one technique that was originally described in the post Invoking Generic Methods on Non-Generic Classes in PowerShell.

The basic idea is to replace the call for ClientRuntimeContext.Load<T> method with the following one:

For invoking a generic methods we utilize MethodInfo.MakeGenericMethod method.

Below are demonstrated some examples of usage SharePoint 2010 Client Object Model (CSOM) in PowerShell.

Example: load Web client object

Let’s start with a simple example for loading Web Client Object:

Example: create Wiki page via CSOM

The example below demonstrates how to create wiki page via CSOM.

C# version:

PowerShell version:

MyFirstWikiPage

Summary

The following article Using PowerShell to Get Data from a SharePoint 2010 List explains how to get the managed client side object model code to work with PowerShell. The proposed solution is to execute generic methods via inline C#  in PowerShell.

References

Access and Manipulate Navigation Settings via SharePoint Client Object Model

Overview

SharePoint Server OM provides  PortalNavigation class that represents navigation for portal pages and other portal navigation objects. In turn the PublishingWeb class  is used to access the navigation settings (PortalNavigation type).

What about Client Object Model? Unfortunately it is not supported to access and manipulate Navigation settings via CSOM since there is no PublishingWeb Client Object  in SharePoint 2010. But still it possible to accomplish via Client Object Model.

Retrieving Web Client Object with Properties

PortalNavigation class uses internally SPWeb.AllProperties property to store Navigation settings and the same type also exist as a Client Object – Web.AllProperties

ClientObject provides a base class for objects on a remote client, the full list of  client objects available in SharePoint 2010 could be found on MSDN page.

When accessing client objects there are some differences that concern how object properties are initialized. According to the MSDN, in the server object model, when you return an SPWeb object, all of its properties become available for use in code. But to improve performance in the client object model, when you return a Web object (JavaScript: Web) certain properties are not included, and you must explicitly retrieve them.

The following example is aimed to demonstrate how to retrieve Web client object with it properties:

Access and manipulate Navigation settings via CSOM

The following class represents Client Object Model (CSOM) implementation of PortalNavigation class:

The following example  demonstrates how to print and update navigation settings using ClientPortalNavigation class :

Summary

Since  Publishing API is not supported in Client Object Model of SharePoint 2010, there is no way to manage  the navigation settings for a publishing site the same way as in Server Object Model. But as was demonstrated in this article it could be accomplished via Web Client Object and Web.AllProperties property.

In turn, in SharePoint 2013 Microsoft.SharePoint.Client.Publishing.Navigation namespace was introduced, in particular WebNavigationSettings class for managing the navigation settings for a publishing site.

References

Embedding Video to a SharePoint Library

Overview

We have already discussed how to embed video from YouTube and another Video Providers into SharePoint, in particular it was demonstrated  how to:

In both cases some kind of customization should be applied for List/Library in order to render YouTube player in List Forms and Views. In first case custom fields are used for storing embed code properties and a computed field for rendering player. In the second case, custom fields are used for storing embed code itself and YouTube player is rendered via customized List View and Field.

This time we will discuss another approach that is intended for sharing video in out-of-the box List and Libraries, like Blogs and Discussion Boards.

How to embed Video in SharePoint Blog and Discussion Board

Before we will dive into technical details about implementation let me show some usage scenarios.

In order to embed a video into SharePoint:

  • On YouTube site click the Share button located under the video.
  • Click the Embed button.
  • Copy VideoId value from  src attribute value provided in the expanded box .
    EmbedYT
  • Add reply  for a Discussion and select Insert Tab – Share VideoYouTube Video Button to insert YouTube video on page
    ShareVideo_Ribbon
  • Specify YouTube Video parameters and click OK button to insert YouTube player on page
    ShareVideo_RteDialog
  • Saved Message item (for Discussion List)
    ShareVideo_Message
  • Blogs View
    ShareVideo_Blogs

Solution

The solution consist of:

  • SharePoint Ribbon and Page Component for Sharing Video
  • RTE with the capability to insert video player
  • Render video player on List Forms and Views

SharePoint Ribbon and Page Component for Sharing Video

1. The existing group Ribbon.EditingTools.CPInsert.Media is extended with the buttons for video sharing.

2. Video Sharing Page component is developed for interaction with the Server Ribbon:

RTE with the capability to insert video player

By default  YouTube video player is rendered as IFrame element. Since in SharePoint 2010 it is not allowed to store iframe content into Publishing HTML field the alternative solution is proposed here:

1. User provides all  the properties for video in RTE dialog
ShareVideo_RteDialogOnly

2. Video player tag is inserted into SharePoint Rich Text Editor from RTE dialog:

3. When the List Form or View page is rendered, YouTube player is created and video is loaded.

Render video player on List Forms and Views

The IFrame player API is intended for embedding a YouTube video player on a website and control the player using JavaScript. The IFrame API posts content to an <iframe> tag on a page.

The code demonstrates how to create an embedded player that will load a video

References

Understanding the List Dialogs setting in SharePoint 2010

Overview

With the introduction of SharePoint 2010 two modes became available  when working with Libraries/List forms   from user experience perspective. Dialogs option in List Settings indicates whether to navigate the full page (Yes) or that the list form page is launched in a modal dialog (No)

XLV_DialogsOption

Figure 1. List settings 

Pay attention to the last part of the description that says:

Note: Dialogs may not be available on all forms.

Interesting, isn’t it, but what exactly does it mean? In order to find out we need to investigate how List Dialogs settings is handled in SharePoint 2010.  So, Let’s get started.

How it works

Depending on which option is selected link events for List/Library forms (New|Edit|View) are handled differently. When the “Launch forms in a dialog” is selected form pages are opened in modal dialog boxes.

How it is implemented

Through SharePoint Object Model the specified List settings for enabling/disabling modal dialog boxes is accessible via  SPList.NavigateForFormsPages property.   As it turns out, the value of  this property is passed to the XSL transform via  XsltListViewWebPart.ModifyXsltArgumentList method:

The XSLT global parameter NavigateForFormsPages  declared in main.xsl file is utilized in CTXGeneration template:

This template is intended for rendering  extra information about List settings on the client side  (ContextInfo structure). It is invoked every time when the List View is rendered on page. Pay attentions that List Dialogs setting that corresponds to NavigateForFormsPages property of ContextInfo structure.

And finally the event handler of the List form links is as follows:

How the List Form link should be handled is determined by the NavigateForFormsPages parameter in the specified function, i.e. :

  • by navigating to a full page using href attribute of link
  • display form in modal dialog box

List Dialogs setting in ListViewWebPart

Now it is time to return to the question about why this settings is not available on all the forms. For answering on that question let me step back and explain a little bit about rendering a List View. Up until now we were talking only about rendering a List View via XsltListViewWebPart  that  handles view rendering for default lists, such as document libraries and announcements. But what about ListViewWebPart that is used for rendering specific List Views like  Calendar, Gantt or Chart Views.

The point is that this parameter (List Dialogs) does not take into account when a List View is rendered via ListViewWebPart. And the message “Dialogs that may not be available on all forms” concerns exactly this situation.

Then the question arise, how do we deal with the case where we need to open List Forms as a full pages for ListViewWebPart?  Let’s consider a real-world example when we need a Calendar forms to be opened as a full pages.

There are several ways how to achieve it, but we will consider only one, one of the simplest. The idea is to specify explicitly NavigateForFormsPages parameter for ContextInfo structure.

Steps:

1. Add CEWP into Calendar View page (Calendar.aspx)

2.  Place the following JavaScript code into CEWP

That’s all, after that the Calendar forms will be opened as a full pages.