Naked Panda Meditations

    sharepointconnector

    1.1.7 • Public • Published

    Build Status bitHound Score

    A Node.js SharePoint Client inherited from sharepointer (by cian clarke) .

    Usage Example

    var sharepoint = require('sharepointconnector')({
      username : 'someusername',
      password : 'somepassword',
      // Authentication type - current valid values: ntlm, basic, online,onlinesaml
      type : 'ntlm',
      url : 'https://sharepointHostname.com'
    });
    sharepoint.login(function(err){
      if (err){
        return console.error(err);
      }
      // Once logged in, we can list the "lists" within sharepoint
      sharepoint.lists.list(function(err, listRes){
          var aList = listRes[0];
        // We can pick a particular list, and read it. This also gives us the list's Items[] and Fields[]
        sharepoint.lists.read(aList.Id, function(err, listRead){
          console.log(singleResult);
        });
      });
    });

    Parameters

    When initialising Sharepoint, there are a number of optional params which can be specified at init. Here are their defaults & descriptions

    var sharepoint = require('sharepointconnector')({
      username : 'someusername',
      password : 'somepassword',
      // Authentication type - current valid values: ntlm, basic, online, onlinesaml
      type : 'ntlm',
      url : 'https://SharepointHostname.com',
      // All of the following params are optional:
      context : 'myCustomerSite', // Set to create resources outside of the base site context, `web`
      verbose : false, // Set to true to stop filtering responses, instead returning everything
      proxy : undefined, // set to string hostname of proxy if running through one
      strictSSL : true, // set to false if connecting to SP instance with self-signed cert
      federatedAuthUrl : 'http://mysamlloginservice.com', // only set for auth type 'onlinesaml', the URL of the SAML service which issues assertions to forward to the SharePoint login URL
      rtFa: <token>,// an optional parameter to set rtFa token value,
      FedAuth:<token> // an optional parameter to set FedAuth token value,  
    });

    Additional Parameters for listing and reading Lists and ListItems

      fieldValuesAsText : true, //Return Lookup Field Values as Text for Items
      filterFields : [{field: 'field1', value: 'value1'}], //Filter Items in List based on field value(s) $filter=
      selectFields : ['field1', 'field2'], //Only return List or Item data for fields specified $select=
      expandFields : ['field1', 'field2'], //"JOIN" another list based on a lookup value and return data $expand=
      orOperator:false, // set to true to enable 'or' operation   
      andOrOperator:false,// set to true to enable 'andor' operation
      $top: "1000" // set the required '$top' value (to change the response cap) and by default it is set to 5000

    A Sharepoint Primer

    Skip this if you already know enough about SharePoint.
    Here's the basics I wanted to know about this product before I began integrating:

    • Sharepoint is a number of products:

      • SharePoint 2013 - the on premise version of Sharepoint which I've seen most often.
      • Sharepoint 365 - the online SharePoint product.
    • Everything is a List in SharePoint. Document Library? A list. The tasks app? Just a list. Discussion Board? You got it, it's a list. Site Pages? List. Turns out, Sharepoint reuses the base type List for a lot of things.

    Methods

    Lists

    As mentioned above, SharePoint is driven by lists. The base SharePoint API allows you to CRUDL lists, but the read operation doesn't return Items[] or Fields[] - this is a separate API operation. With Sharepointer, list read operations also retrieve all Fields[] and Items[] on the list for convenience.

    Lists List

    Confusing, I know. Bear with me. Lists all objects of type list in sharepoints (and remember, almost everything in Sharepoint is a list!).

    sharepoint.lists.list(function(err, listRes,nextUrl){
      // listRes will be an array of lists [{ Id : '1a2b3c', ... }, { Id : '2b3c4d' }, { Id : '5d6e7f' }]
    });

    You can now use any of the following functions to operate upon lists. Note that each lists object in the array will also have a convenience function which operates on itself for read, update & delete. These are also documented below.

    Lists Create

    Creating a result requires a title and a description.

    sharepoint.lists.create({ title : 'My new list', description : 'Some list description' }, function(err, createRes){
      // createRes will be the newly created list as an object { Id : 'list Name', title : 'My new list', ...}
    });

    Lists Read

    List Read can take a string as the first param (assumes list Id), or a params object specifying either a guid or title.
    The list operation already tells us quite a bit about that list, but this read call also returns Fields[] and Items[]. This is different to how the SharePoint API behaves, and is offered as a convenience.

    // Get a list by ID - you can find this under the 'Id' property.
    sharepoint.lists.read('list name', function(err, listReadResult){
      // listReadResult will be an object { Id : 'list name', Title : 'SomeListTitle', Items : [{}, {}], Fields : [{}, {}]  ... }
    });
     
    // Get a list by name
    sharepoint.lists.read({title : 'some list name' }, function(err, listReadResult){
      // listReadResult will be an object { Id : 'list name', Title : 'some list name', ... }
    });
     
    // You can also call a read() operation from an object returned from the list operation for convenience like this
    sharepoint.lists.list(function(err, listRes){
      var aList = listRes[0];
      aList.read(function(err, aListReadResult){
     
      });
    });
     
     

    Lists Update

    Updating requires an ID and a title. Optionally, you can just specify all this in one object.

    // Update specifying the Id separately
    return sharepoint.lists.update('list name', { Title : 'MyNewTitle' }, function(err, updateResult){
      // updateResult will be the object you passed in, but not the full list. To get the fully updated object, a subsequent read is needed.
    });
     
    // Updating specifying the Id in one param
    return sharepoint.lists.update({ Id : 'list name', Title : 'MyNewTitle' }, function(err, updateResult){
    });
     
    // You can also call a update() operation from an object returned from the list operation for convenience like this
    sharepoint.lists.list(function(err, listRes){
      var aList = listRes[0];
      aList.update({Title : '' }, function(err){
     
      });
    });

    Lists Delete

    Delete requires a list Id. Deletion by title is not possible.

    sharepoint.lists.del('someListId', function(err){
      // Err will indicate if somethign went wrong - there's no second param
    });
     
    // You can also call a delete() operation from an object returned from the list operation for convenience like this
    sharepoint.lists.list(function(err, listRes){
      var aList = listRes[0];
      aList.update({Title : '' }, function(err){
     
      });
    });

    List Items

    Lists in sharepoint have a collection of items. These are usually another API call away, but as discussed earlier, sharepointer retrieves these upon performing a read() call.

    ListItems List

    To retrieve the items contained within a list,

    sharepoint.listItems.list('list Name', function(err, itemsUnderThisList,nextUrl){
      //nextUrl -- will provide the next page url and will be used to represent paginated data     
     
    });
    // below method can be used to read complete sharepoint list, irrespective of the pagination SP value it provides the complete data set  (this method will takecare of the pagination internally and provides complete data set).
    sharepoint.listItems.listAll('list Name',function(err, listRes){
     
      });
     
    // will provide the current logged in user details
    sharepoint.listItems.currentuser("list name",function(err,response){
     
    });
    // will provide the binary stream content
    sharepoint.listItems.byteStream("floder Name", "filename",function(err,serviceReqObj){
    // for easy binary handling, invoked the service and piped it to response
        require('request').get(serviceReqObj).on('response', function(response) {
              response.pipe(res);
            });
    });
     
    // below method can be used to read binary content based on the file path
    sharepoint.listItems.byteStreamByFilePath("file Path",function(err,serviceReqObj){
    // for ease of binary handling, invoked the service and piped it to response
        require('request').get(serviceReqObj).on('response', function(response) {
              response.pipe(res);
            });
    });
     

    Of course, we can also just perform a list read:

    sharepoint.listItems.read('list Name', function(err, listReadResult){
      // we now have the items under listReadResult.Items
    });

    ListItem Create

    We can create new ListItems within a list using the create function. The responsibility is on the user to ensure all required fields are included prior to creating a listItem, and no extraneous fields are included. SharePoint throws meaningful & useful errors (..for once) if you include incorrect fields here, so it's easy to debug.

    sharepoint.listItems.create('list Name', { Title : 'My new list item', Remember: 'To include all fields' }, function(err, listCreateResult){
     
    });

    We can also just call .create() on the Items property of a list which we've read.

    sharepoint.lists.read('list Name', function(err, listReadResult){
      // Now that we've read a list, we can create an item under it by running:
      listReadResult.Items.create({ Title : 'My new item' }, function(){
     
      });
      // We could also use listReadResult.createItem() to the same effect
    });

    ListItem Read

    As part of reading a ListItem, we also retrieve it's File property, if any exists. This is helpful, because many lists include a file attachment (e.g. Document Libraries). If no file exists, this will simply be undefined.

    sharepoint.listItems.read('list Name', 'someListItemId', function(err, singleListItem){
     
    });

    Of course, we can also just call .read() on a listItem, after we read it's containing list.

    sharepoint.lists.read('list Name', function(err, listReadResult){
      var anItemInThisList = listReadResult.Items[0];
      anItemInThisList.read(function(err, listItem){
     
      });
    });

    ListItem Delete

    To delete a ListItem, we can use the del() function.

    sharepoint.listItems.del('list Name', 'someListItemId', function(err){
     
    });

    Of course, we can also just call .del() on a listItem, after we read it's containing list.

    sharepoint.lists.read('list Name', function(err, listReadResult){
      var anItemInThisList = listReadResult.Items[0];
      anItemInThisList.delete(function(err){
     
      });
    });

    Why another Sharepoint Client?

    Yet another SharePoint Client. This one:

    • Has test coverage

    • Isn't written in CofeeScript

    • Supports multiple authentication schemas - currently:

      • NTLM
      • Basic
      • Online (Sharepoint 365/Online login flow)
      • Online with SAML SSO (Sharepoint 365 to Federated SAML SSO flow)
    • Accepts pull requests :-)

    Tests

    Tests are written in Mocha. Unit tests simply require the integration tests, and nock the API they integrate with - thus reducing the amount of test code we need to write.

    Running Unit tests

    This includes jshint, and the mocha unit test suite.

    # install grunt globally
    npm install grunt-cli -g
    #run the tests
    grunt test
    

    Running Integration Tests

    #Setup environment variables with your SP creds:
    export SP_USERNAME=YOUR_USERNAME
    export SP_PASSWORD=YOUR_PASSWORD
    export SP_HOST=https://your_sp_hostname.com
    export SP_AUTH_TYPE=(ntlm|basic|online|onlinesaml)
    #Then run the tests:
    grunt integration
    

    Install

    npm i sharepointconnector

    DownloadsWeekly Downloads

    9

    Version

    1.1.7

    License

    MIT

    Last publish

    Collaborators

    • veer_1991