A Node.js SharePoint Client inherited from sharepointer (by cian clarke) .
var sharepoint =username : 'someusername'password : 'somepassword'// Authentication type - current valid values: ntlm, basic, online,onlinesamltype : 'ntlm'url : '';sharepoint;
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, onlinesamltype : 'ntlm'url : ''// 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 everythingproxy : undefined // set to string hostname of proxy if running through onestrictSSL : true // set to false if connecting to SP instance with self-signed certfederatedAuthUrl : '' // only set for auth type 'onlinesaml', the URL of the SAML service which issues assertions to forward to the SharePoint login URLrtFa: <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 ItemsfilterFields : 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' operationandOrOperator: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
Listfor a lot of things.
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.
Confusing, I know. Bear with me. Lists all objects of type
list in sharepoints (and remember, almost everything in Sharepoint is a list!).
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.
Creating a result requires a title and a description.
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;
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;
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;
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.
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:
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.
We can also just call .create() on the
Items property of a list which we've 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
Of course, we can also just call .read() on a listItem, after we read it's containing list.
To delete a ListItem, we can use the del() function.
Of course, we can also just call .del() on a listItem, after we read it's containing list.
Why another Sharepoint Client?
Yet another SharePoint Client. This one:
Has test coverage
Isn't written in CofeeScript
Supports multiple authentication schemas - currently:
- Online (Sharepoint 365/Online login flow)
- Online with SAML SSO (Sharepoint 365 to Federated SAML SSO flow)
Accepts pull requests :-)
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