sharepoint-ruby

A ruby gem that maps Sharepoint's REST API in a simple and accessible fashion.

How to use

First, you'll have to initialize a sharepoint site and open a session in order to start making requests to the REST API:

require 'sharepoint-ruby'

site = Sharepoint::Site.new 'mysite.sharepoint.com', 'server-relative-site-url'
site.session.authenticate 'mylogin', 'mypassword'

blog = Sharepoint::Site.new 'mytenant.sharepoint.com', 'blog', prefix: "sites"
blog.session.authenticate 'user', 'pwd'
lists = blog.lists
for l in lists
  puts l.title
end

Note that site.session.authenticate might throw an exception if the authentication doesn't go well (wrong urls, STS unavailable, or wrong login/password). The exceptions might be of type ConnectionToStsFailed, AuthenticationFailed, ConnexionToSharepointFailed, UnknownAuthenticationError.

Connecting to your own STS

By default, sharepoint-ruby uses Microsoft's STS (https://login.microsoftonline.com/extSTS.srf), which works for Sharepoint Online. You may use your own STS by using the optional third parameter of Sharepoint::Site.new:

site = Sharepoint::Site.new 'mysite.sharepoint.com', 'site-name'
site.session.authenticate  'username', 'password', 'https://sts_url.com/extSTS.srf'

Connecting using NTLM

You may also connect using the NTLM method. For that purpose, you'll have to overwrite the default session handler with Sharepoint::HttpAuth::Session.

require 'sharepoint-http-auth'

site = Sharepoint::Site.new 'mysite.sharepoint.com', 'site-name'
site.session = Sharepoint::HttpAuth::Session.new site
site.session.authenticate 'login', 'password'
site.protocole = 'http' # default protocole is https: don't forget to set this if you use http.

Connecting using Kerberos

You may also connect using Kerberos if you're using MIT Kerberos. For that purpose, you'll have to overwrite the default session handler with Sharepoint::KerberosAuth::Session.

require 'sharepoint-kerberos-auth'

site = Sharepoint::Site.new 'mysite.sharepoint.com', 'site-name'
site.session = Sharepoint::KerberosAuth::Session.new site
site.session.authenticate 'login', 'password'
site.protocole = 'http' # default protocole is https: don't forget to set this if you use http.

General features

Once you're logged in, you may access the site's ressource through the site object:

fields  = site.fields # Get all the site's fields
groups  = site.groups # Get all the site's groups
users   = site.users  # Get all the site's users

lists = site.lists # Get all the site's list
list  = site.list 'Documents' # Get a list by title
list  = site.list '51925dd7-2108-481a-b1ef-4bfa4e69d48b' # Get a list by guid
views = list.views # Get all the lists views

folders = site.folders # Get all the site's folder
folder  = site.folder '/SiteAssets/documents' # Get a folder by server relative path
files   = folder.files # Get all the folder's files

OData mapping

When Sharepoint answers with an OData object, the site.query method will automatically map it to the corresponding Sharepoint::Object class. For instance, if Sharepoint answered with an OData object of type 'SP.List', site.query will return an instance of the Sharepoint::List class. These classes implement a getter and a setter for all the properties declared for the corresponding object in Sharepoint's 2013 Documentation.

N.B: Note that the setter only exists if the property is declared as write-accessible in the documentation. N.B#2: Note that despite the camel casing used by Sharepoint, the getter and setter are snake cased (i.e: the CustomMasterUrl property becomes accessible through the custom_master_url getter and custom_mater_url= getter).

Sharepoint::Object specifics

Sharepoint::Object contains a few methods to help you handle your objects:

The guid method can be used to retrieve the guid of any object.

The reload method returns an instance of the same object from the remote sharepoint site. It may be useful if you want to be sure that your object contains the latest changes.

The save method will automatically compile your changes and perform the MERGE request with the Sharepoint site.

The destroy method will destroy the remote ressource on the Sharepoint site.

The copy method can duplicate an existing object. If you send it a Sharepoint::Object as a parameter, it will duplicate into the parameter. If you don't send any parameter, it will create a new object. Note that no changes happen on the sharepoint site until you've called the save method on the returned object.

Deferred objects

Some of the properties of the OData object are 'deferred', which means that the property only provides a link to a ressource that you would have to get for yourself. Not with the sharepoint-ruby gem however: the first time you try to access a deferred property, the object will on it's own go look for the corresponding remote ressource: the result will be stored for later uses, and then be returned to you.

Modifying Sharepoint's resources

The Sharepoint REST API provides us with methods to create, update or delete resources. In the Sharepoint::Object, these behaviours are implemented through the save and delete methods.

Updating objects

This piece of code will change the custom master page used by the Sharepoint site to 'oslo.master':

  web = site.context_info # Sharepoint::Site.context_info returns the Web object for the current site (see: http://msdn.microsoft.com/en-us/library/office/dn499819(v=office.15).aspx )
  web.custom_master_url = '/_catalogs/masterpage/oslo.master'
  web.save

Creating objects

You may also create your own objects. This will be slightly different: we will create our own instance of a Sharepoint::List object. Some Sharepoint objects have values that can only be set during their initialization: sharepoint-ruby doesn't allow you to set these values through a setter. In the case of list, Sharepoint will require you to specify the value for the BaseTemplate property. This is how you would specify the default value for an attribute that isn't write-accessible:

  list             = Sharepoint::List.new site, { 'BaseTemplate' => Sharepoint::LIST_TEMPLATE_TYPE[:GenericList] }
  list.title       = 'My new list'
  list.description = 'A list created by sharepoint-ruby'
  list             = list.save # At creation, the remote object created will be returned by the save method.

Note that the attribute's name in the constructor remains camel cased (BaseTemplate), though the getter for this attribute is still snake cased (base_template).

Destroying objects

Now, say you want to destroy the list you just created, this will do nicely:

  list.destroy

Parenting

In the previous paragraph, we saw how to create a Sharepoint::List object. Sharepoint lists aren't parented to any other objects: Sharepoint views however are parented to a list. If you wanted to create a view for the list we just created, you would have to specify a parent for the view:

  view               = Sharepoint::View.new site
  view.title         = 'My new view'
  view.personal_view = false
  view.parent        = list # Setting the view's parent to the Sharepoint::List
  view.save

Collections

In sharepoint-ruby, collections are merely arrays of Sharepoint::Objects. If you wish to add an object to a colleciton, set the parent to the object providing the collection.

List Items

Sharepoint doesn't allow the user to fetch more than 100 items per query. When your list contains more than a 100 items, you may fetch them using the find_items method:

  list = site.list 'My List'
  # Use the skip option to paginate
  list.find_items skip: 50 # returns items from 50-150
  # You may use other operators in your query, such as orderby, select, filter and top:
  list.find_items skip: 100, orderby: 'Title asc'

Exceptions

Inevitably, some of your requests will fail. The object sharepoint returns when an error happens is also mapped by sharepoint-ruby in the Sharepoint::SPException class. The SPException class contains methods to inspect the query that was made to the server:

  begin
    list = site.list 'title that does not exists'
  rescue Sharepoint::SPException => e
    puts "Sharepoint complained about something: #{e.message}"
    puts "The action that was being executed was: #{e.uri}"
    puts "The request had a body: #{e.request_body}" unless e.request_body.nil?
  end