Building your first Project Server app : Part 2 – Getting the basic app up and running

In this second post covering how to build an app for Project Server to publish all projects, we will take a look at a new component of Project Server, the JavaScript Object Model or JSOM.

In the past when you wished to interact with Project Server the only real option you had would be to use the PSI, or Project Server Interface, a set of API’s that could be called that would perform tasks within the project server instance like reading a project, creating a resource, or adding a job to the queue.

With Project Server 2013, Microsoft introduced another API called the Client Side Object Model (CSOM) which can be accessed via .Net, Silverlight, and Windows Phone. They also exposed the CSOM via JavaScript and gave it a different name, the JSOM, which is accessible from web pages, custom application pages and the ribbon, which is exactly what we want for our app that will publish our projects.

The new Project JSOM

It’s important to note that the CSOM and JSOM do not expose all the capabilities of the PSI at present, but I understand these capabilities are constantly being updated to the point that in the future we should eventually see parity.

For our app we need to do a few things with the JSOM, firstly, we need to get all of the projects within the Project Web App instance then we need to iterate through them.

To do this:

1. Open up your Napa project and navigate to the App.js file in the script folder. Out of the box Napa will add some default content into the App.js file, select it all and delete the content.

2. Now we are going to add some code to perform the main functions of our app. We need to add some global variables to store the information we will use later and set up to call Project Server for the project data.

// Declare global variables.
var projContext;
var projects;

// Get the projects collection.
function GetProjects() {

    // Display a message to the user to show we are reading the projects.
    $('#spanMessage').text('Reading projects...');
    // Initialize the current client context.
    projContext = PS.ProjectContext.get_current();

    // Get the projects collection.
    projects = projContext.get_projects();

    // Register the request for information that you want to run on the server.
    projContext.load(projects);

    // Run the request on the server.
    projContext.executeQueryAsync(IterateThroughProjects, QueryFailed);
}

The final statement projContext.executeQueryAsync(IterateThroughProjects, QueryFailed) sends the request off to the server and if successful will call IterateThroughProjects or if it failed calls QueryFailed.

3. The real guts of our app is in the IterateThroughProjects function which takes the list of projects and loops through them, checking the project out, publishing it and then checking it back in.

function IterateThroughProjects(response) {
    // Get the enumerator and iterate through the collection.
    var enumerator = projects.getEnumerator();
    while (enumerator.moveNext()) {
        var project = enumerator.get_current();

        // Get the target project and then check it out. The checkOut function
        // returns the draft version of the project.
        var draftProject = project.checkOut();

        // Specify "true" to also check the project in.
        var publishJob = draftProject.publish(true);

        // Register the job that you want to run on the server and specify the
        // timeout duration and callback function.
        projContext.waitForQueueAsync(publishJob, 30, QueueJobSent);
    }
}

Notice how easy it is in the code to check out the project, publish it and drop it back on the queue? Three simple lines of code.

4. Finally all that’s required is to add a bit of error handling code..

// Print the JobState return code, which gives the status of the queue job.
function QueueJobSent(response) {
    if (response == 0) {
        $('#spanMessage').text('Publishing projects...');
    } else
    if (response == 4) {
        $('#spanMessage').text('Projects published...');
    }
}
function QueryFailed(sender, args) {
    $('#spanMessage').text('Request failed: ' + args.get_message());
}

5. And a little bit of code at the beginning to make sure that our JSOM doesn’t kick off until the CSOM library has been loaded and the final code should look like this:

// Declare global variables.
var projContext;
var projects;

$(document).ready(function () {
    SP.SOD.executeFunc('sp.js', 'SP.ClientContext', GetProjects);
});

// Get the projects collection.
function GetProjects() {

   // Display a message to the user to show we are reading the projects.
   $('#spanMessage').text('Reading projects...');

   // Initialize the current client context.
   projContext = PS.ProjectContext.get_current();

   // Get the projects collection.
   projects = projContext.get_projects();

   // Register the request for information that you want to run on the server.
   projContext.load(projects);

   // Run the request on the server.
   projContext.executeQueryAsync(IterateThroughProjects, QueryFailed);
}

function IterateThroughProjects(response) {
   // Get the enumerator and iterate through the collection.
   var enumerator = projects.getEnumerator();
   while (enumerator.moveNext()) {
      var project = enumerator.get_current();

      // Get the target project and then check it out. The checkOut function
      // returns the draft version of the project.
      var draftProject = project.checkOut();

      // Specify "true" to also check the project in.
      var publishJob = draftProject.publish(true);

      // Register the job that you want to run on the server and specify the
      // timeout duration and callback function.
      projContext.waitForQueueAsync(publishJob, 30, QueueJobSent);
   }
}

// Print the JobState return code, which gives the status of the queue job.
function QueueJobSent(response) {
   // Whilst the call is status = 0, i.e happening, then show the publishing message
   if (response == 0) {
	$('#spanMessage').text('Publishing projects...');
   }
   else
   // When the call has come back successfully, show the published message and then navigate back
   if (response == 4) {
        $('#spanMessage').text('Projects published...');
   }
}

// If there is a failure, show it and stay on the page.
function QueryFailed(sender, args) {
   $('#spanMessage').text('Request failed: ' + args.get_message());
}

6. Next we need to update the Default.aspx page in order to call our code and to display what is going on. To do this, open the Default.aspxpage in the Pages folder and replace the contents with the text below:

<%-- The following 4 lines are ASP.NET directives needed when using SharePoint components --%>
<%@ Page Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" MasterPageFile="~masterurl/default.master" language="C#" %>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

<%-- The markup and script in the following Content element will be placed in the <head> of the page --%>
<asp:Content ID="Content1" ContentPlaceHolderId="PlaceHolderAdditionalPageHead" runat="server">

    <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.6.2.min.js" type="text/javascript"></script>
  
	<!-- The following scripts are needed when using the SharePoint object model -->
    <script type="text/javascript" src="/_layouts/15/sp.runtime.debug.js"></script>
    <script type="text/javascript" src="/_layouts/15/sp.debug.js"></script>
	<script type="text/javascript" src="/_layouts/15/ps.debug.js"></script>

    <!-- Add your CSS styles to the following file -->
    <link rel="Stylesheet" type="text/css" href="../Content/App.css" />

    <!-- Add your JavaScript to the following file -->
    <script type="text/javascript" src="../Scripts/App.js"></script>
</asp:Content>

<%-- The markup and script in the following Content element will be placed in the <body> of the page --%>
<asp:Content ID="Content2" ContentPlaceHolderId="PlaceHolderMain" runat="server">
<div id="divMessage" style="text-align:center">
    <br />
    <h1 id="spanMessage"></h1>
</div>
</asp:Content>

7. Before the app can be run we need to the permissions for the app, to do this click on the Properties icon in the bottom left hand corner.

Napa Properties

The properties of the app will be displayed, where you can change the name and other properties of the app. To change the permission click on permissions on the left hand side and find the permission for Projects. Set this to be write.

Setting Properties of the app

This permission allows the app to read & write all projects in the PWA app.

8. Now the main components of the app have been built, click on the Run Project icon to compile and deploy the app.

Napa - Run Project

On clicking Run Project, Napa will take the code, compile it and deploy the app to the developer site automatically ready for testing.

Publish Project to Developer Site

9. Once deployed click on the link in the Launch App dialog to initiate the app. The first time you run the app you will be asked if you trust it the app, choose ‘Trust it’

Do you trust this app?

The app will then run and you will see the following error message, which is perfectly normal.

App Request Failed

The reason the app errors is that it is trying to contact Project Server’s JSOM, but the developer site is not a Project Server site, instead it’s a normal SharePoint site, in order to test our app correctly we need to deploy it over to a PWA site.

10. To publish the app to PWA, click on the publish icon in the bottom left hand corner

Napa - Publish Project for deployment

Napa will then take you through the publishing process and provide a link to the final .app file that we can then upload to our organization specific app store that we can use to deploy our in house built apps called the Corporate catalog. By default, in Office 365 tenant the Corporate catalog is not configured so we have to spend a few moments setting it up.

11. The catalog is now ready to deploy our app. To do so click on New App and choose to upload the app we created in Napa above.

Apps for SharePoint

12. You will be prompted to add additional information for the app including logo’s, icons etc. For now we’ll just leave them and click Save.

Define App Metadata

With that, the app should now be in the Corporate Catalog and ready for us to use in our Project Online instance.

13. To add it to Project Online, open up the PWA site, click on the Gear icon and choose Add an App

PWA - Add an App

14. In the list of available apps you will see our publish app, click on it.

Add the Publish All Projects apps

15. Once again you will be asked if you trust the app, choose to Trust It. After a few seconds the app will be installed and ready to use.

Running the app

To run the app, make sure you have some enterprise projects in your PWA instance. Having an ‘Enterprise Project’ is important, the app will not publish task list linked projects as the publish concept doesn’t exist for these projects.

1. To kick the app off, click on the app tile. The default.aspx page will render and kick off our JSOM code to retrieve the projects, check the projects out and then publish and check them back in. When the projects have published you will see a screen like below.

Publish All Projects - Projects Published!

2. To check the app worked as advertised, click on the Gear icon, choose PWA Settings and Manage Queue Settings. Change the filter to show succeeded queue jobs and you should see all the published projects Smile

Manage Queue Jobs

So there we have it an app that will publish all enterprise projects in a PWA instance using the new SharePoint app model and JSOM. Hopefully you can follow the steps in these blog posts of how to build your own, but in case not, I have shared the Napa project so you can run the project and publish it yourself. To get access to the source go to this link (http://aka.ms/ypwd0c).

In the next post in this series, we will look at how we can submit the app to the SharePoint store to distribute to other Project Server users.

About these ads

9 thoughts on “Building your first Project Server app : Part 2 – Getting the basic app up and running

  1. Pingback: Building your first Project Server app : Part Zero–The introduction « EPMSource

  2. Pingback: Building a Project Server app « Buzz Blog

  3. Pingback: Building a Project Server app « SharePoint (and Project Server) Shenanigans

  4. Hi Alex,
    Thank you very much for this great post!

    I had to change a couple of lines in your code in order for this to work.
    Here’s what I changed:

    App.js:
    Replaced: SP.SOD.executeFunc(‘sp.js’, ‘SP.ClientContext’, GetProjects);
    With: SP.SOD.executeOrDelayUntilScriptLoaded(GetProjects, “ps.js”);

    Default.aspx
    Added:

    Now, when I access the app after published, I see this error in the browser:
    Microsoft.SharePoint.SPException
    The assembly Microsoft.SharePoint.Portal.Proxy, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c does not support app authentication

    Any ideas why that might be?

  5. Hi Alex,

    Quick update: I tried removing this , and I’m now getting the following error:

    Microsoft.SharePoint.Client.ResourceNotFoundException
    Cannot find resource for the request ProcessQuery

  6. I was finally able to list the projects, here’s what I changed. Had to ensure that the PS.js file was loaded before the custom code runs, and the ProjectContext is initialized.
    Hope it helps someone!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s