Node.js, meet SharePoint

Posted on by

In this post I would like to introduce you to Node-SharePoint, a SharePoint client for Node.js available on GitHub and NPM. This Node module allows you to access SharePoint 2010 lists and items from Node.js. It is based on ListData.svc, the OData based REST API for SharePoint 2010. 

Getting started

Download and install Node (if you haven’t already): http://nodejs.org/#download.

This will also install NPM (Node Package Manager). Use NPM to install the SharePoint client module:

C:> npm install sharepoint

A first example

Create a JavaScript file called main.js and use the code below as a starting point:

var SP = require('sharepoint'),
    site = 'http://yourdomain.sharepoint.com/teamsite',
    username = 'yourusername',
    password = 'yourpassword';

var client = new SP.RestService(site),
    contacts = client.list('Contacts');

var showResponse = function (err, data) {
    console.log(data);	
}

client.signin(username, password, function () {
	
    // At this point, authentication is complete,
    // so we can do requests.

    // Example request: Get list items
    // showResponse is used as callback function
    contacts.get(showResponse)

});

Let’s highlight a few key topics:

  • require(‘sharepoint’) returns an ‘namespace’ object, which contains a RestService class.
  • an object of the SP.RestService class represents a client for the ListData service within the designated site.
  • ListData operates on lists, so we use client.list(listName) to create a List object.
  • client.signin implements the claims based authentication process for SharePoint Online. You can find more details about remote authentication in my  previous post.
  • once the signin is completed, the callback function is called. In the callback function you can start sending authenticated requests to SharePoint Online.
  • Please note that the SharePoint client uses the following callback convention:
function callback(err, data) {
   // err: is used to pass an error (string), if any

   // data: contains the output of the previous response or processing step
}

Provide your own credentials and site in main.js and run the file with node:

C:> node main.js

You should see the items of Contacts list in your window:

SNAGHTMLb94bb01

Here are some further example how to work with list items.

// get items ordered by FirstName		
contacts.get({$orderby:'FirstName'}, showResponse);

....

// get fist 3 items and total count of items in list	
contacts.get({$top:3, $inlinecount:'allpages'}, showResponse);

....

// get item with Id 412 from the Contacts list;
contacts.get(412, showResponse);

.....

// add a new item to the list
contacts.add({LastName: 'Peel', FirstName: 'Emma'}, showResponse)

....

// update an item	
contacts.get(412, function (err, data) {

    var changes = {
        // include the changes that need to be made
        LastName: 'Tell',
        FirstName: 'William',

        // pass the metadata from the fetched item
        // this includes the etag
        __metadata: data.__metadata
    };

    contacts.update(412, changes, function () {
        // at this point, the change is completed
        // so let's check by getting the item again
	     contacts.get(412, showResponse)
    })        
})

.....

// delete an item
contacts.del(412);

Hopefully this helps you get going in connecting Node.js to your SharePoint site! Let me know if you have questions/suggestions.

27 thoughts on “Node.js, meet SharePoint”

  3. Do I have just to run npm install sharepoin? I run the latest node.js (v0.7.8-pre) The error I get is: 

    npm ERR! Error: No compatible version found: sharepoint
npm ERR! No valid targets found.
npm ERR! Perhaps not compatible with your version of node?
npm ERR!     at installTargetsError (/usr/local/lib/node_modules/npm/lib/cache.js:486:10)

    I appreciate your help.

    Reply ↓

  4. Pingback: Hello world in node.js « Share… What?

  5. Hi Luc, I finally get some clue how to connect Sharepoint Online, thank you!
    I did all the steps in your tutorial, but if I try “node main.js” I get an error: “Error: Cannot find module ‘sharepoint'”. Any idea what’s wrong?

    Reply ↓

  6. Sorry for getting on your nerves. I did everything like you mentioned but always get the error message: TypeError: Cannot read property ‘value’ of undefined at IncomingMessage.

    Any suggestions?

    Reply ↓

    • Please check the SAML response from the STS server. See if it contains the expected token. The error seems to suggest that the SAML response doesn’t contain the expected token.

      Reply ↓

  8. Hi

    I keep getting this error, any suggestions?

    c:\nodetest>node main.js

    c:\nodetest\node_modules\sharepoint\node_modules\xml2js\lib\xml2js.js:216
    throw ex;
    ^
    TypeError: Cannot read property ‘#’ of undefined
    at c:\nodetest\node_modules\sharepoint\sharepoint.js:121:135
    at Parser. (c:\nodetest\node_modules\sharepoint\sharepoint.js:27:21)
    at Parser.emit (events.js:67:17)
    at Object.onclosetag (c:\nodetest\node_modules\sharepoint\node_modules\xml2js\lib\xml2js.js:183:24)
    at emit (c:\nodetest\node_modules\sharepoint\node_modules\xml2js\node_modules\sax\lib\sax.js:322:32)
    at emitNode (c:\nodetest\node_modules\sharepoint\node_modules\xml2js\node_modules\sax\lib\sax.js:327:3)
    at closeTag (c:\nodetest\node_modules\sharepoint\node_modules\xml2js\node_modules\sax\lib\sax.js:540:5)
    at Object.write (c:\nodetest\node_modules\sharepoint\node_modules\xml2js\node_modules\sax\lib\sax.js:949:29)
    at Parser. (c:\nodetest\node_modules\sharepoint\node_modules\xml2js\lib\xml2js.js:211:31)
    at Parser.parseString (c:\nodetest\node_modules\sharepoint\node_modules\xml2js\lib\xml2js.js:6:61)

    Reply ↓

  9. HI Thanks for ur code ! I tried it according to the specified procedure but i got the following error
    C:\Users\290495\Desktop\nodejs\nodejs\node_modules\node-sharepoint>node main.js

    events.js:71
    throw arguments[1]; // Unhandled ‘error’ event
    ^
    Error: connect ECONNREFUSED
    at errnoException (net.js:769:11)
    at Object.afterConnect [as oncomplete] (net.js:760:19)

    Can u please tell me how to proceed further? Thanks in advance

    Reply ↓

  10. I see you have plans for on premise usage of this node module. Where are you at on this process? I would like to see what I can do to help.

    Reply ↓

    • Not much progress, I am afraid. I would be interested in extending the code to support ADFS, but don’t have a SP environment with ADFS available for testing.

      Reply ↓

  11. extremely helpful code. Thanks so much. I also got the error and it seems the return on my system is slightly different. This fixed the problem even though the code is ugly.

    var token = js[‘S:Envelope’][‘S:Body’][0][‘wst:RequestSecurityTokenResponse’][0][‘wst:RequestedSecurityToken’][0][‘wsse:BinarySecurityToken’][0][‘_’];

    Reply ↓

  13. Nice Post, After creating main.js and passing proper credentials, List, Site URL and running it console it not returning any value/ error. Thank you in advance

    Reply ↓

Leave a reply to lstak Cancel reply