Building your first Project Server App : Part 4 – Submitting to the app store

In this fourth post, I thought it would be fun to go through the process of getting your app up into the Office app store so you can start making millions.

Before you decide to submit your app to the store, you need to do a few things:

  • Read the app store submission guidelines at http://msdn.microsoft.com/en-us/library/jj220035.aspx. These highlight the conditions your app must meet before it will be accepted.
  • Register for a Seller account. Check out http://msdn.microsoft.com/en-us/library/jj220034.aspx how an overview of what info you need to provide and the process of getting one. The Seller accounts can take a few days to come through, so plan ahead and be patient
  • Make sure you have a logo, screenshots and some descriptive text ready for the app submission
  • A version of your .app file that has been compiled for Release.
  • Decided how you are going to licence your app. The app store itself allows you to define how the app will be licenced, will it be free, will it be per purchase, per user, will there be a trial etc. Some of these decisions are not simple and require significant forethought and in some cases additional development work. For our app I decided to keep it simple and go for a free version. Microsoft published a couple of great blogs / articles helping with the licencing over at the Office apps blog.
  • Finally, make sure you have tested, tested and tested your app again, the submission process is very thorough and tests the functionality of your app across not only IE but all supported SharePoint 2013 browsers.

Once all of the above is ready, submitting your app is relatively simple. Navigate to the Seller Dashboard and follow the prompts to submit the app.

First choose a listing type, our app is for Project Server, so we need to choose an app for SharePoint, then click on next.

Seller dashboard - Listing type

In the next screen you will be asked some information about your app like the name, version, category to list it under and some other bits and pieces. The most important part are the testing notes, these are your only real way of passing information through to the testers who are looking at your app.

image

As we are making the app available to everyone, there is no need to choose Trial support. Click on Next.

The final bits to add before you can submit the app are screenshots and some descriptive text and links to support, EULA and Privacy policies.

image

Once you’ve added that text, click on Next and your ready to submit for validation.

From experience, the validation process can take around 3-5 working days. Unfortunately at the moment there is no progress indicator of where you are in the process, with the app either being in a ‘Draft’ or ‘Approved’ state.

Once the app has become approved, it takes a few hours for it to propagate down into the SharePoint app store and to become available for everyone to download and start using.

In conclusion

I hope these posts have shown you that creating an app for Project Server, or for that matter, SharePoint in general is really really simple. Through the various options for hosting apps, either in SharePoint, in Azure, or on your own infrastructure and the investments in APIs such as oData, Rest, JSOM & CSOM, there is an incredibly powerful set of tools available for you to leverage. As we saw, you don’t need expensive tools, with Microsoft making available free tools such as Napa, Visual Studio Express or even NotePad that can be used to build your first app.

Through some of the other investments, such as the corporate catalog and the Office Marketplace, Microsoft look to have provided options for both the hardened enterprise user and casual small business user to gain access to either enterprise specific software, or fully tested  third party software which can be bought with the simplicity of buying an app for your mobile phone. I am certainly looking forward to seeing the richness of some of the apps being offered through the app store.

 

Update: The final app is now available for download in the SharePoint app store http://office.microsoft.com/en-us/store/publish-all-enterprise-projects-WA103982215.aspx?redir=0. If you find it useful, please submit a review.

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.

Building your first Project Server app : Part 1 – Getting Started – Setting up a development environment

In this first post on how to build an app for Project Server to publish all projects, we will look at setting up your development environment.

Before we start, for the purpose of these posts we are going to leverage an Office 365 based Project Online tenant. Using Office 365 takes away some of the pain of setting up your own server environment and can be provisioned in a fraction of the time. It should also be noted that whatever works on Office 365 will also work on premise, so we can rest assured that our app will work in all environments.

The process of signing up for online account is relatively simple and takes about 20 minutes to provision. To sign up for a tenant, click here and following the prompts. Once the tenant is provisioned you need to create a special ‘Developer site collection’ by creating a new Private Site Collection with the developer template.

SharePoint Developer Site

To start building our app, we are going to use an app itself that Microsoft created called ‘Napa’. To install Napa, click on the Build an app tile and you will be redirected to the store to install the ‘Napa’ tools. They will install when you click on the ‘Add it’ button.

Napa Office 365 Development Tools in App store

Once it is installed, the Napa app will be available to use, click on it to open up the web based Napa editor. Napa is a really cool technology providing a web based development environment in the cloud that you can develop apps in and then at the touch of a button push them down into your SharePoint environment.

When the Napa editor has loaded, choose to create an App for SharePoint and name the app Publish All Projects.

What type of app do you want to build?

Napa will then go off and create a template for your app which you can then fill in.

Napa Online Editor

Setting up the corporate catalog

The second thing we need to set up is a location to deploy our apps to within the tenant called a Corporate Catalog. Whilst SharePoint has a public app store, it also has an organization specific app store that you can use to deploy your internal apps into.

In Office 365, choose SharePoint from the Admin menu.

SharePoint menu

On the left hand menu, choose Apps.

Manage SharePoint Apps

Choose app catalog. The first time you do this, Office 365 will ask you to create a new app catalog, choose ‘Create a new app catalog site’ and click on OK and then enter the requested details.

Create App Catalog

Once the site is provisioned, navigate to it and click on Apps for SharePoint.

App Catalog

In the next post, we will use the developer site and Napa to build our first app for Project Server.

Building your first Project Server app : Part Zero–The introduction

PublishAllLogoOne of the many exciting additions to Office 2013 was the introduction of apps, through these apps it is possible to add, extend and enhance the functionality available to users, for example you could have an app to help track election results, add Facebook social to your sites or build workflows. The apps themselves are available for a number of the desktop clients, as well as SharePoint 2013 and Project Server 2013.

The idea behind apps in SharePoint is pretty simple, instead of allowing users to deploy what are known as ‘Full Trust Solutions’ to the SharePoint environment (these are solutions that execute code directly on the SharePoint servers) that could destabilise or alter SharePoint and impact it’s availability, Apps allow the same functionality to be hooked in remotely. The key to the app model is some clever architecture, allowing apps to be run either inside an isolate app site within SharePoint (known as SharePoint hosted), within a Microsoft Azure instance (Auto Hosted) or remotely on a providers infrastructure (known as Provider hosted).  Through a number web friendly technologies such as oData, REST and CSOM, these apps can hook into SharePoint and Project Server seamlessly as if they were still installed on the same servers.

The apps, once built are available to be added to your SharePoint and Project Server sites from a central app marketplace. There are two options to choose from, a Microsoft hosted and operated app store, where apps are submitted, validated and then made available for download either at cost, or in a trial mode. Or if an organisation has developed their own app that they just want used internally, they can be deployed to a organisational app store called the Corporate Catalog (we’ll talk more about that later on).

SharePoint App Store

Of course the great thing about apps and the Microsoft ecosystem in general is the information and tooling that is provided for you to build and customise these apps. Microsoft has spun up a dedicated blog and developer site to guide you through the concepts, requirements and process of building apps.

So where is all this going?

Well, I thought I would set out to build an app for Project Server. Thanks to an idea from a mailing list and some discussion amongst some of the Project MVPs, I decided to set out to build an app that when installed in PWA, allows you to publish all Enterprise Projects at the click of a button.

There is a fair amount of things to cover, so I have created a number of posts to cover the various topics:

    So make sure you stay tuned over the next few weeks

Smile