InstantQuick Technical and Office 365 App Marketplace Week 2 Diary

I’m a couple days late getting this post up, but the analytics in this post cover the same range of days as last week’s entry.

App Updates

This past week we pushed two sets of updates for Instant Legal Practice and Instant Consulting Practice.

The Updates

The first on the 17th fixed a number of issues and made some improvements in the time billing system. I use the apps to run my consulting business and based on a few things I noticed creating invoices for the first half of the month there are some more tweeks to come. These fixes were delivered by our application services.

The second set of updates changed the app packages to request additional permissions, the first was Read on the site collection. This was required to fix an issue that prevented the creation of content types in app webs installed in subsites. It turns out that this is necessary because the parent content types are part of the site collection’s root web. I will write about the provisioning of content types in an upcoming post.

The other update added a request for app only permissions that will allow impersonation when persisting settings to fix an error when users who are a not site owners attempt to update settings or generate invoices.

The changes for additional permissions required a resubmission via the seller dashboard. We submitted both apps on Friday 9/13 and received approval on Monday for one app and on Tuesday for the other. We watched and the new versions appeared in the marketplace late on Tuesday, but it wasn’t until Thursday that the apps prompted us on our test site that an update was available.

New users will get the new version but old users will not receive the update until they accept the update via the link shown in the screenshot above. How long will it be until we can implement the change affecting users with member access? We will need to implement additional code on our end to check a user’s version and prompt them to apply the update! Even then they could ignore the update so we will need code to accommodate that situation as well.

Lessons Learned

The primary takeaway is that you should always ask for the highest permission set you think your app will ever need. Getting an update to all of your users later on will be complicated and time intensive. The amount of time required for any update and the fact that such updates to the app package are always optional requiring user consent is another reason we do not like SharePoint hosted apps in the marketplace and prefer our hybrid model or pure provider hosted apps.

Stats, Analysis, and Disappointment in Google

Downloads per day were similar in weeks one and two. We still have not begun any advertising or promotion and we figure it is still too early to expect much word-of-mouth. Therefore this is organic traffic coming from views in the Office 365 marketplace. If the trend continued with no advertising or promotion we would have 1000 installs in a little under six months.

Of course not everyone who installs one of the apps uses it after checking it out. The usage pattern from the first two weeks breaks down as follows:

A little over half never used the app after the first download, but as I wrote last week, half of these people hit a bug that prevented the installation from completing. Over half of the people who managed to complete the install came back another day and there are now real people using the apps to run their small practices!

Trouble with Google Analytics

The InstantQuick site is new and has migrated content from the now retired Elumenotion.com site. I was very concerned when I decided to make the change that Google and Bing would punish the move and we’d lose traffic from search. We use Google analytics on this site as we did on the old site, but this site uses the newest tracking script where the old site used the script from 2007 when that site launched. Looking at the analytics data it appears that the drop in traffic was much worse than expected, but it turns out that there is good evidence that the numbers Google is providing aren’t anything close to accurate!

Earlier this week I wrote a technical post titled Design Tips for SharePoint 2013 Apps on Tablets and Subnotebooks. This site uses Feedburner to syndicate content via RSS and the RSS feed is in turn used by a few content aggregators. Among them is a site I recommend, Planet SharePoint. According to this single aggregator 143 people followed their link to my content in the first day it was available.

Feedburner’s statistics have been unreliable for a long time and they have become even less reliable lately oscillating wildly from day to day so I don’t put much stock in their reporting. But their stats say there were 48 clicks on that article in the feed and that only 10 of them were from Planet SharePoint.

Google Analytics tells me that the page was viewed 13 times.

I’ve done a few other things to confirm this using other pages, but it looks like my Google Analytics numbers are off by over a factor of 10!

Although I am much more interested in the usage patterns of the apps I will need to get to the bottom of this Google problem soon or find a new way to measure traffic on this site!

Design Tips for SharePoint 2013 Apps on Tablets and Subnotebooks

If you’ve ever thought about doing a startup you are probably familiar with the idea of the minimal viable product. For Instant Legal Practice and Instant Consulting Practice we decided that this meant focusing on a great experience within Office 365 and Microsoft Office and on some sophisticated backend designs that make it possible for us to be nimble and continuously improve the products. What we want to know is if there is a viable business in Office 365 apps and if our ability to continuously update the products will give us a strong competitive advantage.

Knowing our goals we decided early on that we were not going to invest heavily in different form factors beyond the desktop but that it would be good if we could make the products usable on tablets. Both products are tested and work on IPad 2 (and later), Nexus 7, Galaxy Tab, and Windows Surface. On the IPad they work in Safari. On the Android tablets they work in Firefox and Dolphin, but surprisingly not Chrome for Android which is a shockingly bad browser.

Tip 1: Responsive Design

If you are working on a publishing site or you intend to make big changes to the look and feel, a responsive design is your best bet. Here are a couple of links to get you started: Pro SharePoint 2013 Branding and Responsive Web Development and http://responsivesharepoint.codeplex.com/.

This was not a viable option for us because we don’t use a custom master page as a principle for compatibility with other apps and because our apps depend on list views and the ribbon for much of the user interface. It is probably something that could be made to work for us, but I think it would be a major effort and it is pretty far down the roadmap.

Tip 2: Keep required width to a minimum

This one is pretty obvious. On these devices the base resolutions vary in landscape mode, but most are 980 pixels wide. There are meta tags, CSS, and JavaScript techniques that allow some control over the viewport and zoom behaviors, but as I said we want to keep our initial investment to a minimum and so we focused on making sure the columns in our tabular layouts look good in no matter the width of the browser.

Tip 3: Use CSS effectively

The detail pages for different entities like clients and matters consist of a table at the top and often a set of tabs at the bottom that show related data.

The number of columns in the header varies by entity and also based on the data. In the case of the Clients view the Phone Numbers, Address, and Notes columns are hidden if there is no data.

The tables present challenges because the browser width varies and the width required to display specific data inside the tables also varies. However, using the base of 980 pixels wide gives us a lower bound and we set the min-width of the main content area to 900px and the width of the table to 97%. Finally, in the subordinate elements the vertical alignment is top, there is explicit padding, and the word-break is normal. All, in all, pretty basic stuff.

Tip 4: Leverage the ‘Focus on Content’ Button

The Focus on Content button is located in the upper-right hand corner of the page.

By default, when you click it, it hides all of the chrome including the menus and focuses on the content.

Not focused on content

Focused on content

This could be a great feature, but it was apparently designed by the same folks who figured app webs don’t need menus! It would be better if you didn’t have to continuously touch the button to navigate between pages.

The other day I wrote about Custom Navigation in App Webs. In that post I showed how we use JavaScript to supply menus in the apps. The same script has a monkey-patch to intercept the Focus on Content button and ensure that the primary navigation remains visible.

This is the normal view on an IPad2:

Not focused on content

It is usable if you scroll, but it works much better if you focus on content:

Focused on content

The script is fairly simple.
var oSetFullScreenMode; //Stores the original function in the SharePoint libraries

//If the function exists assign it to the variable for the original function
if (typeof (SetFullScreenMode) !== 'undefined') {
   oSetFullScreenMode = SetFullScreenMode;
}

//Replace the function with a new function
SetFullScreenMode = function (fEnableFullScreenMode) {
   //If the user is enabling full screen mode

   if (fEnableFullScreenMode) {
      //Add some margin to the top of the content area
      $('#contentBox').attr('style', 'margin-top: 20px;');

      //And put the menu into the content area as its first element
      $('#contentRow').prepend(nav);
   }
   else {
      //Otherwise remove the margin and the menu
      $('#contentBox').attr('style', 'margin-left: 220px;');
      $('#contentRow').find('#DeltaTopNavigation').remove();
   }
   //And then run the original function so SharePoint can take care of the rest
   if (oSetFullScreenMode !== undefined) {
      oSetFullScreenMode(fEnableFullScreenMode);
   }
};

//When the page loads, check to see if it is already in fullscreen mode based on the pressence of the ms-fullscreenmode
//if the page is not a dialog add the marging and insert the menu
var bodyElement = document.body;
if (bodyElement != null) {
   if ($(bodyElement).hasClass('ms-fullscreenmode') && !window.location.search.match("[?&]IsDlg=1")) {
      $('#contentBox').attr('style', 'margin-top: 20px;');
      $('#contentRow').prepend(nav);
   }
}

 

Tip 5: Don’t put options in the quick launch that aren’t available elsewhere

The presumption is that if you are using a tablet you will stay focused on content. On our billing pages, the Generate Invoices link is only on the quick launch and therefore obscured to tablet users. We will move it in an upcoming update.

Tip 6: Turn off Minimal Download Strategy

This is not a concern if you are in an app web, but in host web scenarios, this feature created the most compatibility issues in the browsers we tested. Fortunately it is easy to detect and disable minimal download strategy with CSOM.
clientContext.Load(clientContext.Web.Features);
clientContext.ExecuteQuery();
var mds = clientContext.Web.Features.GetById(new Guid("87294C72-F260-42f3-A41B-981A2FFCE37A"));
if (mds != null)
{
   clientContext.Web.Features.Remove(new Guid("87294C72-F260-42f3-A41B-981A2FFCE37A"), true);
        clientContext.ExecuteQuery();
}

Tip 7: Size dialogs dynamically on open

The above tips dealt with width, but you also need to worry about height if you are using the dialog framework. When you show the dialog set the options based on the page’s natural height.
var options = {
   url: lps.WebUrl + '/FormsAndDialogs/Matter/NewMatter.aspx',
   title: 'New Matter',
   allowMaximize: false,
   showClose: true,
   height: 576,
};
SP.UI.ModalDialog.showModalDialog(options);

Then resize it by calling the following function from the page contained in the dialog.
function resizeDialogWorkspace() {
   //If the dialog is taller than the window make it shorter than the window
   if (window.innerHeight < jQuery('#s4-workspace').height()) {
      jQuery('#s4-workspace').height(window.innerHeight - 6);
   }
}

This is what the dialog looks like on a Nexus 7.

Custom Navigation in App Webs

Of the things that I most dislike about app webs is the lack of support for navigation. There is no provision for a top link bar or quick launch and if you try to add items to the web’s Navigation collection you will get an error. Fortunately it is easy to create these menus with a little JavaScript.

Don’t Touch the Master Page

Like most folks in SharePoint land we use jQuery in Instant Legal Practice and Instant Consulting Practice whenever we need to change what SharePoint serves. We could have used a custom master page, but one of our guiding principles is to avoid such customizations of the host environment because an app that requires modification of global resources, like master pages, will not coexist well with other apps. Therefore none of our apps touch the master page and we always attack these sorts of problems in the client with script.

Know your URL

Generating a site’s navigation on the server has certain advantages. One is that SharePoint automatically produces correct links based on the web’s server relative URL. You need this information to do this work on the client, but figuring it out programmatically on every page load is inefficient. Therefore one of the things we provision when the user installs the app is a dynamically created JavaScript file that contains this sort of environmental information used throughout our scripts.

Getting the HTML and Making it Seamless

Although we go out of our way not to customize global resources we always want it to look like we did. Normal users should not be able to tell what is custom and what is not – we want everything to be seamless and feel like a natural part of the platform. Because of this, when we need HTML we almost always derive it from the original using Firefox or Chrome. Prior to IE 11, IE’s developer tools aren’t good for this task because the DOM inspector doesn’t show dynamic content and the menus are dynamic.

To get the HTML, simply select the element and copy the HTML to the clipboard.

Getting the navigation HTML with Firebug

This technique ensures that the resulting menu will look stock and will also respond to custom themes and design packages.

Putting it together

Once you have the HTML and the current web’s URL the rest is easy. Simply modify the HTML to include the desired menu items with a token for the web URL, replace the token with the actual URL, and insert the HTML into the page.

The end result looks like this:

The creation of the custom quick launch uses the same basic techniques.

Author: Doug Ware

InstantQuick Technical and Office 365 App Marketplace Week 1 Diary

Last week we submitted free versions of Instant Consulting Practice and Instant Legal Practice to the marketplace as a soft launch with no advertising other than this blog. For the next few weeks we will continue to give the basic apps away while we shake out the problems found by real users. This post is about what we learned technically and our experience with the marketplace.

Office 365 App Marketplace Stats

At the moment the listings are for English US which limits our target market a bit. The apps are new they aren’t on the first page of the store and so we had pretty low expectations for the first week. We were pleasantly surprised. According to the seller dashboard we had a total of 42 installations and 1341 browser hits and a review.

As expected, the Instant Consulting Practice had more downloads, but we were contacted by three organizations this week and two of them were small law firms. It seems our market research was valid and there are enough people looking at the store that we are getting views in spite of not being on the front page.

Usage Notes

Most of the functionality of these apps is implemented on our servers. Since we generally don’t know who are customers are and don’t store any personally identifiable information, it is important that we have some decent analytics to understand usage and identify problems.

Of the organizations that tried the app, 20% used it more than once and most of them have used the app they downloaded several times. We figure that we have around a dozen active users after one week.

Unfortunately, 20% of the organizations that tried to install the apps did something we didn’t test for and their installations failed! Most of those who experienced the error did not try again.

Technical Notes

There was an issue loading a javascript file and fixed the second day the apps were live. There was another issue that affected the viewing of individual invoices and we fixed it on day 5. We were able to push these fixes with little delay because of the way our systems are built.

Unfortunately, the big bug that affected the ~20% of installations that failed occurs when you attempt to install the app on a subsite instead of the root site of a site collection. Fixing this requires more permission than the original app packages have, but we identified the problem and implemented a fix. Because this affects the apps permissions we must repeat the app validation process with Microsoft to update the apps and prevent the problem from recurring in the future.

All in all, a great first week!

How to Install and Uninstall Apps from the SharePoint Store on Office 365

The other day I was giving a friend of mine who has an existing Office 365 subscription a tour of Instant Consulting Practice. I was a bit surprised that he had never installed an app nor did he know how or what it would do to his site.

Adding an App

There are two ways to add an app. Select Add an app from the gear dropdown or navigate to the Site Contents page and click the add an app icon.

Method 1 – from the gear dropdown

Method 2 – from the Site Contents page

In either case you will see a list of all the various built-in apps available on your SharePoint site. To see the apps available on the marketplace click the SharePoint Store link located on the left side of your screen.

There are many apps in the store organized by category. Select the category from the list on the left and then select the app – in this case Instant Consulting Practice.

Don’t be scared!

Clicking an app doesn’t add it to your site; it takes you to a page where you can learn more about the app before you commit to the installation. Once you feel comfortable, and you are ready, click ADD IT.

 

You still have a chance to change your mind. Every app contains a policy that tells you what permissions you are giving the app in your site. Instant Consulting Practice and Instant Legal Practice both use the minimum available permissions. To begin the actual installation of the app click Trust It.

The Site Contents page loads and shows that your app is installing. You can still cancel the install if you change your mind!

Once the app package is installed on your site the icon will become solid and you can click it to launch the app.

Some apps need to do additional setup before you can use the app. The Instant Practice Manager products do additional work when the app is launched for the first time and occasionally to deploy updates and fixes.

Once the app is ready the home page displays and you can use the app.

What if I don’t like the app I just installed?

Installing an app from the store is safe because it doesn’t change the site where you install it. Instead, it gets its own site. To get rid of the app, click the link in the upper-left corner of the page to return to your site and then navigate to the Site Contents page.

Next, hover over the app icon, and click the ellipses to display the hover card, click its ellipses, and click Remove.

Warning!

Removing the app will remove everything you put in the app including any documents you uploaded! You will receive a warning and there is no going back.

Conclusion

If you are into SharePoint you may have read articles or blog posts about the app model. For better or worse most of the restrictions Microsoft has in place in the store are there so that you can feel comfortable installing an app and know that it won’t mess up your site. If you’d like to give it a try, why not go install Instant Consulting Practice or Instant Legal Practice for free?

Sandbox Solutions – Not Completely Dead

Recently Richard diZerega (whose blog you should be reading) wrote a post called SharePoint Sandbox isn’t Dead…UserCode is wherein he explained that the use of sandbox solutions for declarative provisioning via CAML with features is not deprecated but that the use of procedural code within the sandbox user code host is deprecated. This got some folks talking because none of the official Microsoft docs make this clear.

Today I was part of a large email thread where Iouri Simernitski from the Visual Studio Tools for Office team said the same thing. When asked if that was the official word he said that it was and that this fact was not secret or subject to any NDA’s – we should feel free to share this information publicly.

So, if you have a sandbox solution and you want to maintain it going forward in a supported way, keeping your modules, fields, content types, list instances, etc. in CAML is an option. You can migrate the procedural code to CSOM, JSOM, or REST as needed. It won’t be compatible with the Office 365 marketplace but it will be supported.

Author: Doug Ware

Host Web versus App Web Case Study – Clients

App Web versus Host Web in Office 365 Apps

Chris O’Brien and I have had a running conversation about the merits of using the host web versus the app web as the container for app functionality. If you’d like to catch up on the conversation, it has gone thusly so far:

In Chris’s last post he softened his position a bit. This post is an actual example that compares the client management features in the free trial versions of Instant Practice Manager (the ones in the marketplace) which use app webs to the standard versions which use host webs (which we sell directly because they use a higher level of permissions than the marketplace allows).

Office Integration

On the surface the two versions are hard to tell apart, but in a ghetto web app web there are no rich client integration features like Outlook and document library synchronization and this difference has a profound effect on the user experience.

Clients view in app web

 

Clients view in host web

When Outlook is available you can connect the list to Outlook and create or edit clients in Outlook as well as perform mail merges.

Not to mention features for individual contacts.

You get similar benefits with the calendar and task features.

Document Synchronization

Document synchronization is another major advantage of a host web compared to an app web. The screen shots below show the Documents tab in the app web version and in the host web version.

App Web

Host Web

 

A synchronized document library is a huge time saver, especially if you have folder structures you always want to copy or many documents that you need to file.

Working with the client’s documents in Windows Explorer

Synchronized with the client in SharePoint

This synchronization capability is something that can be leveraged in so many cases. It works particularly well when combined with a document scanner like the Fujitsu ScanSnap.

There are many more advantages to using a host web (and upgrading to the standard edition of Instant Practice Manager) that I won’t go into here, but hopefully this will convince Chris that choosing an app web over a host web is not something you should do automatically. The choice will make a big difference to your users!

Technical Notes

There is only one code base. All provisioning is done via CSOM in processes hosted in a Windows Azure worker role. The architecture is fairly complex, but the code itself is relatively simple. The key is that using features in an app package is to be avoided because they only support app web deployments.

I will be announcing public training classes soon and as always, we’d love to hear from you if you need consulting help or would like to license the framework. If you are interested in either please send us an email at info@instantquick.com.

Author: Doug Ware

New Products, New Site and New Name

Introducing InstantQuick

Almost two years ago I began working on a legal practice management system for Office 365 based on the sandbox architecture. I was almost done with that solution when I found out about the new app model.

After much soul searching I decided not to release the original but instead to attempt a rewrite. My reasoning was simple, if I released I’d have to spend time in the future rewriting anyway and I’d still have to rebuild as an app. This required a leap of faith on my part because I wasn’t very happy with the limitations of the sandbox but I was also pretty skeptical about the new model. I liked the architectural direction and it was in line with what I had done in my first version, but I had doubts about the API’s and the execution. I wrote several articles about my thoughts that are in this site’s archive but I eventually became very happy with what I was able to accomplish as an app.

Over the same period of time I read (and sometimes debated) other articles on the blogosphere about apps. Most were about the merits of the model and how to go about building them. Eventually I stopped because I didn’t have time and also because the whole concept is pretty squishy and tough to discuss in the abstract. Instead I thought, ‘In a few weeks I’ll launch and then people will see what I’m talking about!’

I’ve been saying that for many months now.

I’m happy to say that the trial versions of the apps are now in the Office 365 marketplace approval process and that the full versions will be available in the next couple of weeks.
The apps are: Instant Legal Practice and Instant Consulting Practice.

The apps are designed for small practices and they make it easy to track clients, matters and projects, meetings and tasks. Best of all they include powerful time tracking and billing features including automatic invoice generation. Going forward there will content both about how they work under the covers and how to get the most out of the features. That is why this site is divided into two sections.

Before I close this post let me say that my technical and usability goals for these apps are audacious. I want to set the bar for what a SharePoint app can be and I am very happy with the result. Barring any unforeseen circumstances they’ll be available sometime this week. I hope you’ll check them out.

Thanks,

–Doug

P.S. I’d like to thank my wife and children for putting up with my insane schedule and my friend, and fellow SharePoint MVP, Dan Attis for letting me use his house as a place of solitude.