Alexander Vanwynsberghe

"There is nothing impossible to him who will try"

How to boost your event with Yammer

Last week, we (Ensoné) presented at the Yammer Ignite Prague re-delivery organized by Microsoft Belgium. The reason I’m writing this blog post is because we actually managed to use Yammer to boost our event. (Funny: “An event about Yammer, on Yammer”) We succeeded in our mission! With 20 participants, we had more than 100 conversations, 250 replies and  200 likes in just one day!

logo Read More

How to use Project Server Online data in a SharePoint 2013 App using CSOM

This week I was attending the 3 day Project Ignite training. This is a technical training offered directly from Microsoft and was presented by Christophe Fiessinger and Jan Kalis at Warsaw (but I followed the training on Lync, which was really cool using the 360-video). I learned lots of new and interesting things about Project Server 2013 and Project Online. Thanks Christophe and Jan!

Of Course, that’s not the topic of this blog post. During the last day of the training, we got some information about the extensibility options for Project Server 2013. One of the topics was about CSOM, which is an abbreviation for Client-Side Object Model, and also about JSOM, which stands for Javascript Object Model. Let me use the slide from Project Ignite explaining what it is all about:

As you can see, an interesting topic to do some deep diving and (as Christophe told us to) doing our homework. I’ll guide you through the process of creating:

  1. A console application, connecting to my local Project Server 2013 lab machine and create a project.
  2. A SharePoint Autohosted app (based on my previous blogpost: Windows Azure auto-provisioned apps for SharePoint 2013), connecting my Project Online PWA instance using OAuth 2.0 and retrieving a list of projects.

1. Local Console Application

To start, I will create a small piece of code to create a project on my local Project Server 2013 lab machine. So no SharePoint app, no authentication, just creating a project using CSOM. To start, open your Visual Studio 2012 and create a new Console Application. The first thing you have to do with this empty console project is referencing 3 DLL’s. If you’re developing on a machine with Project Server 2013 installed, you can add a reference directly, otherwise you need to copy the 3 DLL’s to your development machine (create an ‘Assemblies’ folder in your project) and reference them this way. The 3 DLL’s you need can be found in the folder “%ProgramFiles%\Common Files\Microsoft Shared\Web Server Extensions\15\ISAPI\ “. Copy those items:
  1. Microsoft.ProjectServer.Client.dll
  2. Microsoft.SharePoint.Client.dll
  3. Microsoft.SharePoint.Client.Runtime.dll

Reference them in your project and open ‘Program.cs’. Add the code, listed here, to your application. I’m not going to repeat every piece of code, as it’s explained very well on that link. But what I want to mention is ‘security’. If you run your SharePoint/Project Server 2013 dev environment, and you develop your application on another machine, you need to provide credentials to connect to SharePoint/Project Server, in fact, you need to initialize the ProjectContext with those credentials. The ProjectContext contains the client-side context for development with a Project Web App instance, and contains the enterprise-wide collections of Project Server objects that exist in Project Web App. You can get the ProjectContext using your credentials with the following quick and dirty solution:

If you run the application (after you added the following command to the start-options of your project: -n “Test Project using CSOM 01” -t 20) , you should see:
In general, it’s all about the ProjectContext. Using this context, you can do/get whatever information you want. In this case, a new Project is created using the object ‘ProjectCreationInformation’, this object is added to the ‘projContext.Projects‘ and finally you tell the context to update with this new project. This will create a queue job and will perform the required action. That was easy to do!

 

2. SharePoint Autohosted App

In this part, I will create a SharePoint Autohosted App where I will use the CSOM to retrieve a list of all projects. You can find a step-by-step guide in one of my previous posts. What you will need  is a subscription of Project Online Preview  (of course). If you haven’t got a  subscription yet, you should really try it out (more info can be found in this post). The first step is to create a new “App for SharePoint 2013” project using Visual Studio:
On the next screen, you should enter the URL of development site (note: when you want to debug Apps on SharePoint Online, you need to have a site collection created as ‘Development site’ type. Otherwise, you will receive an error while publishing in debug mode). This option does have an impact when you want to try debug apps for Project Server (using PWA), but more about that later.
No you have an empty SharePoint App. In our case, we want to use this app to get a list of projects stored on our online PWA. If you look at the files in your project, you will see a file called ‘TokenHelper.cs‘. This is a file responsible for the OAuth 2.0 authentication of your application with SharePoint. It includes the code to handle OAuth 2.0 authentication and how to perform callbacks to SharePoint using CSOM. More information about SharePoint 2013 authentication can be found here.
This TokenHelper class is used to get a SharePoint ClientContext, like you can see in the code below. The TokenHelper returns an authenticated instance of the ClientContext, which is the CSOM you can use to create some cool things.
This is great for SharePoint, but we need something different, we need a ProjectContext. This ProjectContext object inherits from ClientContext in SharePoint,  so you can also access the SharePoint CSOM through this ProjectContext object. To get this context, we need to change some small things to the TokenHelper class. Create the following 2 new functions in TokenHelper.cs
Now we have can get our ProjectContext using the “GetProjectContextWithContextToken” function. We can use the following code just to output the list of Projects:
What it basically does is loading the Projects into the ProjectContext and execute the query to get the results. Ok, now that you have the code, you should manage the permissions of the App. Because will we ‘read’ data from Project Server, we will need this permission to be able to actually read the data. The permission configuration settings can be found in the AppManifest.XML. You can find this file in your Solution Explorer. When you open this file, Visual Studio will show you an editor where one of the option is about permissions. Add the permission ‘Projects Read’ to this list and save the file:
Allright, we have the code and the permissions for our App are set. The next thing is, how can we debug this app? Well, remember when you created the project. We’ve added the URL to our Development site on SharePoint online environment. This development site is a seperate Site Collection. The first problem with that is the fact that this Site Collection does not contain a PWA instance. So if we debug our current application, we will never get data. The second problem is about the permissions. When you try to debug the application, it will check the permission settings. Because we created a permission ‘Projects Read’, we will always get an access denied error, simply because there is no PWA there. So, debugging the application on a Development Site Collection will give you:
You could also try to debug it directly on the PWA site (by changing the debug URL), but then you get this error when debugging:
I passed the question about this to Christophe, and he forwared my question to Eli Sheldon (Program Manager at Microsoft). He gave me this explanation (Thanks!):

SharePoint added a site collection level feature near RTM that, once enabled, will allow you to F5 deploy from VisualStudio, no matter what type of site collection you are targeting. Until the new bits roll online and this is documented, your best option here is to F5 debug on-prem and publish an app package and use the corporate catalog to test online.

So as you can see, currently no F5 debug with this release. But the RTM is coming really soon! (Should be there around mid November for MSDN subscribers). So for now, just publish the App and install it on our Project Server Online environment.  Right-click on your project containing the AppManifest file and select ‘Publish‘. You will get this dialog:
Click finish, and the output folder of your .APP file should open. Now we should ‘upload‘ it to our SharePoint Online environment, and make it available for the users. The place where App’s are managed is called the “App Catalog“. This app catalog is a separate Site Collection, and can be created using the SharePoint Administration Center. There you can click on ‘Apps – App Catalog‘. If you haven’t created one yet, it will create one for your, and otherwise, you will be redirected to the App Catalog itself. On your App Catalog site, click on ‘Apps for SharePoint‘ (on the left side). You will see an overview of all installed apps, including an indication of the licenses you still have available. To add your App, click ‘New Item‘ or drag and drop your .app file to the top area of this page.

Now you have your new Application available in the App Catalog. To use it, just go to Project Server Online PWA. Go to ‘Site Contents‘ on the left side, and click on ‘Add an App‘. There you should see the application we’ve just uploaded. Click the App, and you should get a question to confirm the required permissions. In our case, reading Project data. Trust this and continue. When the process is ready, your application is installed on your site, and you’re ready to use it. Click on the App, and you should see:

That’s a list of your projects, retrieved by the ProjectContext (CSOM). Nothing fancy, no HTML, just plain text. Cool! Now it’s up to you to use the CSOM and create some great apps! I’m really excited about this way creating apps, the way CSOM works, the flexibility, the (future) debugging.

 

3. The things we learned 

  1. You can do lots of things with the ProjectContext
  2. Don’t forget to setup your Permissions in the AppManifest file
  3. You can’t debug until RTM

Thanks to my colleague Koen Callens for the fun experience of creating our first App together! Thanks for reading, and enjoy creating your Project Server apps!