{"id":17123635,"url":"https://github.com/plaristote/sharepoint-ruby","last_synced_at":"2025-04-05T11:13:12.568Z","repository":{"id":16399310,"uuid":"19150169","full_name":"Plaristote/sharepoint-ruby","owner":"Plaristote","description":"A ruby client for Sharepoint's REST API.","archived":false,"fork":false,"pushed_at":"2024-07-29T12:08:41.000Z","size":95,"stargazers_count":64,"open_issues_count":7,"forks_count":52,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-29T10:11:27.279Z","etag":null,"topics":["ruby","sharepoint","sharepoint-online","sharepoint-ruby","sharepoint-site"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Plaristote.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-04-25T15:09:01.000Z","updated_at":"2024-12-30T22:21:44.000Z","dependencies_parsed_at":"2024-10-30T05:24:36.262Z","dependency_job_id":null,"html_url":"https://github.com/Plaristote/sharepoint-ruby","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Plaristote%2Fsharepoint-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Plaristote%2Fsharepoint-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Plaristote%2Fsharepoint-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Plaristote%2Fsharepoint-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Plaristote","download_url":"https://codeload.github.com/Plaristote/sharepoint-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247325696,"owners_count":20920714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ruby","sharepoint","sharepoint-online","sharepoint-ruby","sharepoint-site"],"created_at":"2024-10-14T18:26:48.195Z","updated_at":"2025-04-05T11:13:12.552Z","avatar_url":"https://github.com/Plaristote.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"sharepoint-ruby\n===============\nA ruby gem that maps Sharepoint's REST API in a simple and accessible fashion.\n\nHow to use\n===============\nFirst, you'll have to initialize a sharepoint site and open a session in order to start making requests to the REST API:\n\n```Ruby\nrequire 'sharepoint-ruby'\n\nsite = Sharepoint::Site.new 'mysite.sharepoint.com', 'server-relative-site-url'\nsite.session.authenticate 'mylogin', 'mypassword'\n\nblog = Sharepoint::Site.new 'mytenant.sharepoint.com', 'blog', prefix: \"sites\"\nblog.session.authenticate 'user', 'pwd'\nlists = blog.lists\nfor l in lists\n  puts l.title\nend\n```\n\nNote that site.session.authenticate might throw an exception if the authentication doesn't go well (wrong urls, STS unavailable, or wrong login/password).\nThe exceptions might be of type ConnectionToStsFailed, AuthenticationFailed, ConnexionToSharepointFailed, UnknownAuthenticationError.\n\n### Connecting to your own STS\nBy 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:\n\n```Ruby\nsite = Sharepoint::Site.new 'mysite.sharepoint.com', 'site-name'\nsite.session.authenticate  'username', 'password', 'https://sts_url.com/extSTS.srf'\n```\n\n### Connecting using NTLM\nYou may also connect using the NTLM method. For that purpose, you'll have to overwrite the default session handler with `Sharepoint::HttpAuth::Session`.\n\n```Ruby\nrequire 'sharepoint-http-auth'\n\nsite = Sharepoint::Site.new 'mysite.sharepoint.com', 'site-name'\nsite.session = Sharepoint::HttpAuth::Session.new site\nsite.session.authenticate 'login', 'password'\nsite.protocole = 'http' # default protocole is https: don't forget to set this if you use http.\n```\n\n### Connecting using Kerberos\nYou may also connect using Kerberos if you're using *MIT Kerberos*. \nFor that purpose, you'll have to overwrite the default session handler with `Sharepoint::KerberosAuth::Session`.\n\n```Ruby\nrequire 'sharepoint-kerberos-auth'\n\nsite = Sharepoint::Site.new 'mysite.sharepoint.com', 'site-name'\nsite.session = Sharepoint::KerberosAuth::Session.new site\nsite.session.authenticate 'login', 'password'\nsite.protocole = 'http' # default protocole is https: don't forget to set this if you use http.\n```\n\n### General features\n\nOnce you're logged in, you may access the site's ressource through the site object:\n```Ruby\nfields  = site.fields # Get all the site's fields\ngroups  = site.groups # Get all the site's groups\nusers   = site.users  # Get all the site's users\n\nlists = site.lists # Get all the site's list\nlist  = site.list 'Documents' # Get a list by title\nlist  = site.list '51925dd7-2108-481a-b1ef-4bfa4e69d48b' # Get a list by guid\nviews = list.views # Get all the lists views\n\nfolders = site.folders # Get all the site's folder\nfolder  = site.folder '/SiteAssets/documents' # Get a folder by server relative path\nfiles   = folder.files # Get all the folder's files\n```\n\n### OData mapping\nWhen Sharepoint answers with an OData object, the `site.query` method will automatically map it to the corresponding Sharepoint::Object class.\nFor 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\nN.B: Note that the setter only exists if the property is declared as write-accessible in the documentation.\nN.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).\n\n#### Sharepoint::Object specifics\nSharepoint::Object contains a few methods to help you handle your objects:\n\nThe `guid` method can be used to retrieve the guid of any object.\n\nThe `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.\n\nThe `save` method will automatically compile your changes and perform the MERGE request with the Sharepoint site.\n\nThe `destroy` method will destroy the remote ressource on the Sharepoint site.\n\nThe `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.\n\n### Deferred objects\nSome 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.\nNot 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.\n\n### Modifying Sharepoint's resources\nThe 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.\n\n##### Updating objects\nThis piece of code will change the custom master page used by the Sharepoint site to 'oslo.master':\n```Ruby\n  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 )\n  web.custom_master_url = '/_catalogs/masterpage/oslo.master'\n  web.save\n```\n\n##### Creating objects\nYou may also create your own objects. This will be slightly different: we will create our own instance of a Sharepoint::List object.\nSome 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.\nIn 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:\n```Ruby\n  list             = Sharepoint::List.new site, { 'BaseTemplate' =\u003e Sharepoint::LIST_TEMPLATE_TYPE[:GenericList] }\n  list.title       = 'My new list'\n  list.description = 'A list created by sharepoint-ruby'\n  list             = list.save # At creation, the remote object created will be returned by the save method.\n```\nNote that the attribute's name in the constructor remains camel cased (`BaseTemplate`), though the getter for this attribute is still snake cased (`base_template`).\n\n##### Destroying objects\nNow, say you want to destroy the list you just created, this will do nicely:\n```Ruby\n  list.destroy\n```\n\n### Parenting\nIn 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:\n\n```Ruby\n  view               = Sharepoint::View.new site\n  view.title         = 'My new view'\n  view.personal_view = false\n  view.parent        = list # Setting the view's parent to the Sharepoint::List\n  view.save\n```\n\n### Collections\nIn 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.\n\n### List Items\nSharepoint 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:\n\n```Ruby\n  list = site.list 'My List'\n  # Use the skip option to paginate\n  list.find_items skip: 50 # returns items from 50-150\n  # You may use other operators in your query, such as orderby, select, filter and top:\n  list.find_items skip: 100, orderby: 'Title asc'\n```\n\n### Exceptions\nInevitably, 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.\nThe SPException class contains methods to inspect the query that was made to the server:\n\n```Ruby\n  begin\n    list = site.list 'title that does not exists'\n  rescue Sharepoint::SPException =\u003e e\n    puts \"Sharepoint complained about something: #{e.message}\"\n    puts \"The action that was being executed was: #{e.uri}\"\n    puts \"The request had a body: #{e.request_body}\" unless e.request_body.nil?\n  end\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplaristote%2Fsharepoint-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplaristote%2Fsharepoint-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplaristote%2Fsharepoint-ruby/lists"}