Alex's blog on all things Microsoft Project & Project Server

Menu

Category Archives: Development

Post navigation

In case you had missed the news, Microsoft have announced The Appies, a competition around creating an awesome app for SharePoint, Office 2013 or our favorites, Project Server, Project Online or the Project client (Jeremy had the scoop a few weeks ago and coined the Appies name which I think is pretty apt).

To qualify for the Appies, all you need to do is submit a new app or update an existing app between November 25th 2013 and January 31 2014 to be automatically entered.

So what can I win you may be asking?

Well, if you’re an app developer or vendor, the prize is pretty awesome, expanding the reach and promotion of your app by being:

Tech Ed Australia is being held on the Gold Coast between the 3rd and 6th September this year. I am happy to announce I will be speaking at Tech Ed Australia this year with my partner in crime, Mr Brian Farnhill with an awesome session entitled….

Office 2013 has brought an amazing new platform for developers to take advantage of, in the format of apps and the online app store. SharePoint 2013 takes full advantage of this and developers can now publish apps to the store and get their products out to a bigger audience than ever before with minimal time and effort. But if you have an idea for the next big app, how do you go about building it and publishing it for the masses? Well then my friend, this is the session for you! During this session Brian and Alex will take you through the full process for building and publishing apps for SharePoint and Project Server 2013 to the store. The boys will share with you the techniques and strategies you will need to create apps that will engage and amaze users, as well as what to do with an app to help make sure it makes its way through the app stores approval process and on to the app store. You’ll get to see real world stories and learnings from apps that are available on the store today, as well as what potential issues you might come across while working with your own apps. If you have ever thought about building an app or are in the process of creating one, this session is a must see!

One of the most obvious differences between Project Server 2013 and 2010 is the look and feel, specifically the new modern UI style tiles to help you perform tasks / find options quickly and easily called ‘The Carousel’. On a un-customised PWA site you will see two rows of these tiles, the ‘Getting Started’ and the ‘Track your work’ options.

For a while I have been thinking about how powerful one of these carousels would be within your own organisation, perhaps providing a direct link to view the queue, a link to that report everyone uses, a central lessons learned register, a PMO site, or even your favourite EPM / PPM blog. Whilst recently catching up on the Project blog, I noticed this post talking about how how the carousels were based on SharePoint’s promoted links app, so thought I would see how easily I could create my own customised carousel.

Creating the Promoted Link app.

In your PWA site (In this post, I have used Project Online, but you could also do this in your on premises Project Server 2013) , click on the Settings (Cog) icon and choose ‘Add an App’

In the ‘Your Apps’ screen, you can either scroll through the available apps, or do as I did and choose to search for ‘Promoted’.

Click on the Promoted Links app, you will then be prompted to give it a name. In this case I am going to call it ‘EPMSource Links’ and click on Create.

The app will then be added and ready for you to start customising.

Adding content to your app

Click on the EPMSource Links app to open it, you will see an empty screen advising that you can add new links from the ‘All Promoted Links’ view.

Click on the ‘All Promoted Links’ view to open up the correct view, then click on the ‘Add Item ‘ to add your first piece of content.

A new item screen will be displayed where links themselves can be configured.

My Queued Jobs Link

To start with I am going to create a link through to the My Queued Jobs page (MyJobs.apsx). As the carousel is visual, I also need to create a 150 x 150 image to show up, in this case I have artistically created a large white Q on a green square and uploaded it to the Site Collection Images.

Then fill in the following items:

Title, this is what will show up on the individual item in the carousel

Background Image, this is what will show up as the contents of the tile

Description, this is info that will be showed when the mouse hovers on the tile

Link Location, this is the location the browser will go to when the tile is clicked

Launch behaviour, this determines if the link opens in the browser, a new browser or a dialog box

Order, used to order the tiles when there are more than one.

When your happy, click Save.

Adding a link to external content

Following the above steps, add a second item with the following settings:

This time the tile will be the second one and link out to this blog.

If you’ve done everything right, you should see something like this

Adding the Promoted links to the PWA page.

The final step to use our links is to add it to the front page, thankfully that’s pretty easy.

On the PWA home page, click on the Settings (Cog) and choose Edit Page.

Click on the ‘Add a Web Part’ link for the zone where you want to add the links. The Add Web Part UI will be displayed, allowing you to choose a web part, or in our case, an ‘App part’ to add to the page.

Make sure you select the Apps category, then the EPMSource Links, then click on Add.

The app part will then be added to the PWA homepage, click on Stop Editing and you should see something like this.

As you can see, it’s pretty easy to customise and add new links to Project related content via the Promoted Links app. Of course you are not just limited to doing this in PWA, the Promoted Links app is also available in SharePoint, so you can add a similar customisations to your Project workspaces and SharePoint sites.

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.

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.

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.

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.

In this post, we will take our app that we built in Napa and successfully tested and export it out to Visual Studio to enhance the app, specifically we are going to add a ribbon button so our app can be invoked directly from the PWA ribbon.

Exporting the Napa solution out to Visual Studio

Whilst Napa is a great tool, at the moment it is not possible to add a CustomUI Action at present, so we need to use Visual Studio. Luckily Napa has a handy export to Visual Studio capability. Before we export, make sure you have Visual Studio 2012 installed and have downloaded and installed the Visual Studio Tools for Office 2013 from http://t.co/lrkaq4au (this is currently Preview 2).

To export the project, in Napa click on the ‘Open in Visual Studio’ icon

You will be prompted for which language you wish to export using, our app is all JavaScript so it doesn’t really matter, but I usually pick C#

Napa will prompt you to download a small .exe file that will open Visual Studio and the exported project.

As you can see, our app has been opened in Visual Studio 2012 with all the components you would expect to see

To add our ribbon button, we need to add a new item to our app project. To do so, right click on the project name and choose Add > New Item

From the menu, select Ribbon Custom Action, name it and click Add.

A dialog will pop up asking to configure the custom action. Make sure you choose to expose the custom action in the host web (in our case the PWA instance) and that it is scoped to None (we don’t want it on a list, but rather the ribbon). Click on Next.

Another dialog will pop up asking us to provide a target location, label text etc. Unfortunately the options it provides are a little limited for Project Server, so we will accept the defaults (by clicking Finish) and edit them later.

For our app, we want to add a new group to the Project ribbon in Project Center, and pop our button in there, like so…

To do this we need to define a new group, the button and a graphic in the XML, which follow the usual format for a SharePoint / Project Server ribbon customisation. However there are a couple of changes in 2013 with regards to ribbons:

We can’t have JavaScript in the ribbon – which means instead of calling our App.js from the ribbon like we would have in 2010, now we have to call the default.aspx page and get that to do the work

We need to use a special token ~appWebUrl to tell SharePoint to navigate to the app web which resides under the host web (PWA)

We will also pass through the {StandardTokens} query string that contains information about the site calling the app, including language and most importantly it’s location.

In Visual Studio, replace the contents of the Elements.xml file for the custom action with the following:

In the XML above, I have cheated and used one of the out of the box buttons for Project Server, but you could add your own in the Images folder of the solution and reference it.

Next, we need to make some minor changes to the to the App.js file to ensure return the page back out of the app when it’s completed. To do this replace the QueueJobSent() function as per below.

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) {
// Navigate back to the calling page
var spHostUrl = decodeURIComponent(getQueryStringParameter('SPHostUrl'));
// We're in an iFrame, so make sure you use the top
window.top.location.href = spHostUrl;
}
}

We also need to add another function called getQueryStringParameter which reads the query string from the SPHostURL (part of the {StandardTokens}.In this case here I am borrowed some code to read the query string used in a couple of Microsoft app examples.

With that all the development is complete, all we need to do is come up with a graphic that will be seen in SharePoint, the app should have a transparent background if you want it to fit in with Project Server 2013’s new look and feel themes. Once you have built an icon, add it into the Images folder of the solution and configure the Icon in the App Manifest.

Now all we need to do is build the app, deploy it to the corporate catalog and add it back to our PWA instance.

Installing our new improved app will now show a button on the ribbon in the Project Center that when clicked will navigate out to our Publish Projects page and then once complete, navigate back to the calling site.

So you can see how simple and easy it was include a new button on the ribbon that calls our app directly, publishes the projects and then returns the user to the source site.

In the final post in this series, I will take you through the submission process to make your app available in the SharePoint app store to start making millions

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.

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 &quot;true&quot; 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..

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 &quot;true&quot; 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:

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.

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.

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.

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

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’

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

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 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.

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.

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

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

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.

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

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.

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.

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.

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.

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

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.

On the left hand menu, choose 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.

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

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