A Node.js SharePoint Client inherited from sharepointer (by cian clarke) .
Usage Example
var sharepoint = username : 'someusername' password : 'somepassword' // Authentication type - current valid values: ntlm, basic, online,onlinesaml type : 'ntlm' url : 'https://sharepointHostname.com';sharepoint;
Parameters
When initialising Sharepoint, there are a number of optional params which can be specified at init. Here are their defaults & descriptions
var sharepoint = 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!).
sharepointlists;
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.
sharepointlists;
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.sharepointlists; // Get a list by namesharepointlists; // You can also call a read() operation from an object returned from the list operation for convenience like thissharepointlists;
Lists Update
Updating requires an ID and a title. Optionally, you can just specify all this in one object.
// Update specifying the Id separatelyreturn sharepointlists; // Updating specifying the Id in one paramreturn sharepointlists; // You can also call a update() operation from an object returned from the list operation for convenience like thissharepointlists;
Lists Delete
Delete requires a list Id. Deletion by title is not possible.
sharepointlists; // You can also call a delete() operation from an object returned from the list operation for convenience like thissharepointlists;
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,
sharepointlistItems;// 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).sharepointlistItems; // will provide the current logged in user detailssharepointlistItems;// will provide the binary stream contentsharepointlistItems; // below method can be used to read binary content based on the file pathsharepointlistItems;
Of course, we can also just perform a list read:
sharepointlistItems;
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.
sharepointlistItems;
We can also just call .create() on the Items
property of a list which we've read.
sharepointlists;
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
.
sharepointlistItems;
Of course, we can also just call .read() on a listItem, after we read it's containing list.
sharepointlists;
ListItem Delete
To delete a ListItem, we can use the del() function.
sharepointlistItems;
Of course, we can also just call .del() on a listItem, after we read it's containing list.
sharepointlists;
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