A few weeks ago I had the pleasure of presenting ‘How to build Cloud Hosted SharePoint Apps with Ruby on Rails’ at the SharePoint Conference 2012 in Las Vegas. This was quite a challenging topic as not only is the whole SharePoint App model generally new to everybody, but most .NET developers only know how to develop around the Microsoft stack. Someone however remembered that I had done some Ruby on Rails a couple of years ago and so my name was put forward for this topic. Although we were at a Microsoft SharePoint conference, thankfully some others also found this topic interesting (I was totally worried about having an empty room). Even if you aren’t a Ruby on Rails developer, the things I cover in this series of blog posts will be useful if you want to use anything other than .NET such as php, django, java etc…
Also this certainly should not be used as an example on best practice Ruby on Rails development. But what I do hope to provide is a guide so your Rails developers can get going quickly on the bits and pieces around SharePoint 2013 Apps.
So would I choose to build a SharePoint App in Ruby on Rails? If I was starting a brand new project I would stick to .NET and ASP.NET MVC/Webforms as the tooling within Visual Studio 2012 really is fantastic. But if you have an existing application built on Rails or your team of developers has a ton of Rails experience – then there is now no technical reason why not to make use of your existing investment in code or skills.
For this demo we are going to make use of an Office 365 Preview tenant, Visual Studio 2012 with the Preview 2 of SharePoint Tools, and build our actual Rails App on MacOS.
Let’s get going…first we are going to register a new app in Office 365. From within the admin screens of Office 365 make sure you have a Site Collection created using the Developer Site Template.
Upon having this created, browse to the site collection. We need to register our SharePoint App with Office 365 and Azure Access Control Services (ACS). For development purposes we can register our new application using the appregnew.aspx page within Office 365. There is no link to this page so you need to type the direct url straight into your browser. The url will be something like:
https://[office365previewtenant].sharepoint.com/sites/[dev site collection]/_layouts/15/appregnew.aspx
Make use of the Generate buttons to create an app id and secret for you. Give your application a nice friendly name and enter the following values for domain and redirect url
Domain : localhost:3001
Redirect Url : https://localhost:3001
Using appregnew.aspx registered our application with Azure Access Control Services. Only us and ACS know what our app’s secret will be, so the string of characters generated will be used to decode information coming from SharePoint/ACS. Make sure you note down the app id and especially the app secret as you will not be able to get access to it again.
As we are only using this App for dev/test purposes registering it with appregnew.aspx if perfectly fine. If we wanted our App to be listed in the official SharePoint Store and be publically available we would need to register an account over at the Seller Dashboard (https://sellerdashboard.microsoft.com) and register our application there.
Visual Studio
We do still need to do some work in Visual Studio to create our app package that will be uploaded to SharePoint. Open up Visual Studio (via ‘Run as Administrator’) and create a new project. Under the Office/SharePoint project node create a project using the ‘App for SharePoint 2013’ template.
You’ll be asked what type of SharePoint App you want to create…
Give your app the same name you gave in appregnew.aspx and enter the url of your Developer site collection. Make sure you choose a Provider-hosted app type as the hosting model.
In the last wizard screen, leave the top option selected ‘Use a client secret’
Upon clicking OK you will see 2 projects created in Solution Explorer
The first project is our SharePoint App which will generate the app package that will be uploaded. The second project is an ASP.NET webforms project that Visual Studio automatically created for you. It presumes you want to build your Provider-hosted app using ASP.NET – little does it know how crazy we are that we want to use Ruby on Rails. Needless to say we can ignore this project.
Double click on AppManifest.xml contains all the details about our app. When the Manifest Designer opens up set the following values:
Start Page : https://localhost:3001
We need to grant our App various permissions to be able to read and write data to the SharePoint site where our app is installed. We can do this through the permissions tab. You should only request the minimum permission set your app needs to function. The more permission’s your app requests, the less likely it is to be installed as people will be concerned that your app is a security risk.
As it happens in this particular set of blog posts we want to show quite a lot of functionality within our Ruby on Rails app and so we are going to ask for the following permissions:
| Scope | Permission |
| Micro Feed | Write |
| Tenant | Write |
| User Profile | Read |
As of writing, if you want your app to write to a sites Newsfeed you will need to request Write permissions across the entire Office 365 tenant. This is because when your app writes to a sites newsfeed it also writes to the persons My Site feed – and so needs a lot of permissions.
Save and close the AppManifest designer.
I’ve had some hit and miss results as to whether the next step is needed – but doing it certainly doesn’t hurt you so you might as well. In solution explorer right-click on AppManifest.xml and choose ‘Open with…’. From the list choose to open with the ‘XML (Text) Editor’
When AppManifest.xml is open, simply insert the App Id you registered in appregnew.aspx for the value of RemoteWebApplication ClientId
Now we are good to deploy. Press F5 within Visual Studio 2012 and it will package up your app and deploy it to your Developer site collection within Office 365. If you are prompted to login – go ahead. Once you are in and your app has been deployed you will be presented with the request to trust your new app.
Notice how all the permission requests are listed so the user knows exactly what your app will be able to do. The more permissions you request, the scarier this will look! But as we are building a test project go ahead and trust it 😎
You should be transported off to https://localhost:3001. An error page will be displayed because currently nothing exists at this url – we need to create and configure our Rails app to respond to requests made.
And here ends our development in Windows. You can now use Bootcamp or whatever setup you have to switch to MacOS so we can start building our Rails app.
Apple MacOS and Ruby on Rails
For this walkthrough I am using Ruby version 1.9.3 and Rails version 3.2.8
We will need a few Ruby Gems installed to be able to work with SharePoint 2013 and the Rest web services. These are:
jwt – for decoding the JSON web token that comes from SharePoint
rest-client – for making rest requests to SharePoint
nokogiri – nice library for querying the XML which is returned from SharePoint
Go ahead and create yourself a new Ruby on Rails application in your favourite code folder by typing into Terminal:
rails new SharePointDemo
Rails will now go and great an entire MVC (model – view – controller) web application for us. I will be using TextMate for coding, so once rails has stopped generating things move into the directory and type into the Terminal window:
mate .
Open up the gemfile and below gem ‘jquery-rails’ add in the gems that we downloaded as part of the pre-reqs.
gem ‘jwt’
gem ‘rest-client’
gem ‘nokogiri’
This step is similar to adding a new reference to an assembly/dll in Visual Studio.
Configure for https
You may have noticed when we registered our app in appregnew.aspx we set the Redirect Url to be https://localhost:3001. SharePoint 2013 and our SharePoint App will be using OAuth to be able to authorize our application and user – and a major part of the OAuth specification is that both of the communicating ends need to be https. This is understandable as you would not want someone naughty intercepting un-encrypted access tokens being transmitted across the internet as they could then in theory have access to your Office 365/SharePoint site.
Rails uses WEBrick by default as it’s built in webserver. You can consider WEBrick to be the same as IISExpress that comes with Visual Studio. When you create your rails web app and run it, WEBrick will be configured to listen to http traffic on port 3000. There are a number of steps you need to do to configure WEBrick to be able to use a test/temporary SSL certificate so we can get it listening on https://localhost:3001. Thankfully this blog post has all the steps needed to generate the certificates and configure rails to use them:
Welcome back, hopefully that all went smoothly. Now you should be able to run rails:
bundle exec ruby script/secure_rails s
And browse to https://localhost:3001. You will get a warning about the certificate being trustworthy – but as we created this certificate ourselves for test purposes we can ignore the warning and trust it.
Hopefully you should see the Welcome to Rails screen!
Now if you browse to your Developer site collection on Office 365, in the Recent Items list on the Quick Launch bar you should see a link to your app. Click on this, and you should be redirected to our rails app and again see the ‘Welcome to Rails’ screen!
Congratulations! You have just built your first Ruby on Rails SharePoint 2013 app! It doesn’t do very much (or anything if we are being honest!), but it is a start – and from here we can begin to build great things.
Check back shortly for the next blog post in this series where we shall start working with the Context Token sent to our SharePoint Rails App by SharePoint, and communicating with Azure ACS to get an Access Token.
<nickswan/>
