Dot Net Mafia

How to: Get a Result Source Id in SharePoint 2013

CoreyRoth — Tue, 21 May 2013 15:45:00 GMT

Result Sources in SharePoint 2013 are quite powerful. However to make use of them in your queries, you have to know the Id which you pass to the SourceId parameter of a query. For out-of-the-box result sources, the Ids are static. When you start creating your own though, you need a way to retrieve the Ids programmatically. Unfortunately, the only way to retrieve the Ids is to use the managed API. This means they can’t be retrieved using JavaScript or REST. With that aside, I still wanted to show you how you could write managed code to retrieve a result source id.

For today’s example, I am going to build a console application, but you could also implement this in a web part or other code directly executing on a SharePoint server in the farm. Whenever you build a console application using SharePoint, be sure and change the platform target to x64. Then, we need to add a few references which we can find in the ISAPI folder of the 15 hive. Add the following assemblies to your project.

Microsoft.Office.Server
Microsoft.Office.Server.Search
Microsoft.SharePoint
Microsoft.SharePoint.Security

In our code, we’ll need a heap of assemblies to get started. Add the following using statements.

using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;
using Microsoft.Office.Server.Search;
using Microsoft.Office.Server.Search.Administration;
using Microsoft.Office.Server.Search.Administration.Query;

Next, we need to get a reference to the Search Service Application Proxy so that we can retrieve the result source. There are a number of ways to do this, but I am going to get it by name.

SearchQueryAndSiteSettingsServiceProxy settingsProxy = SPFarm.Local.ServiceProxies.GetValue<SearchQueryAndSiteSettingsServiceProxy>();
SearchServiceApplicationProxy searchProxy = settingsProxy.ApplicationProxies.GetValue<SearchServiceApplicationProxy>("Search Service Application");

Once you have a proxy object, it is easy to get the result source and then the id. The proxy object has a method GetResultSourceByName method. You can pass it the name of the result source you want, but you also need to specify a SearchObjectOwner object to specify which level you want to access it at (Service Application, Site Collection, or Site). I’ll show you each one starting with Service Application. In my example, I have result resources created at each level.

This creates a SearchObjectOwner for the site collection.

SearchObjectOwner serviceApplicationOwner = new SearchObjectOwner(SearchObjectLevel.Ssa);

Next we pass it as the second parameter to GetResultSourceByName. The first parameter is simply the name of the result source.

SourceRecord serviceApplicationResultSource = searchProxy.GetResultSourceByName("Service Application Result Source", serviceApplicationOwner);

Assuming, there is a matching result source, all you need to do is use the Id parameter on the SourceRecord object.

Guid serviceApplicationResultSourceId = serviceApplicationResultSource.Id;

You can then use that Id in your own queries using the SourceId keyword.

If you want to reference a result source at the site collection or site level, you need to do a few extra steps. Start by getting a web object. You need this whether you are using a site collection or site and I’ll show you why shortly.

using (SPSite site = new SPSite("http://sp2010/sites/test"))
{
    using (SPWeb web = site.OpenWeb())
    {
 
    }
}

Inside our using block, we’ll add our code. Let’s get things at the site (web) level first. We do this by creating a SearchObjectOwner specifying a SearchObjectLevel of SPWeb and passing a second parameter containing our SPWeb object.

SearchObjectOwner siteOwner = new SearchObjectOwner(SearchObjectLevel.SPWeb, web);

Now, we pass the SearchObjectOwner to the GetResultSourceByName method like before.

SourceRecord siteResultSource = searchProxy.GetResultSourceByName("Site Result Source", siteOwner);

Like before, we can use the Id parameter to get the id of the result source.

To access result sources at a site collection, the API is a bit different than what you might be used to. We create a new SearchObjectOwner object and we specify a SearchObjectLevel of SPSite. In this case, we also pass it the SPWeb object from before even though we want the site collection. It’s a bit different but it works. Here’s what it looks like.

SearchObjectOwner siteCollectionOwner = new SearchObjectOwner(SearchObjectLevel.SPSite, web);
SourceRecord siteCollectionResultSource = searchProxy.GetResultSourceByName("Site Collection Result Source", siteCollectionOwner);

That’s all it takes to get a result source id. As I mentioned earlier, it is unfortunate that we can’t get a result source id any other way, but this will work if you are writing managed code in on-premises SharePoint 2013.

Slides and code samples from my Search talk at SharePoint Summit Toronto

CoreyRoth — Thu, 16 May 2013 14:42:53 GMT

I’ve had yet another fun week up here in Canada. I gave a brand new talk about the new ways to query search in SharePoint 2013. I had a room full of developers that asked a lot of great questions. As promised, my slide deck is below at SlideShare.

Five ways to query SharePoint 2013 Search

In the session, I mentioned that I had code samples on MSDN Code, so I am providing the link below. Try them out and download them and rate them if you find them useful.

SharePoint 2013 Search Samples

Follow me on twitter: @coreyroth

SharePoint 2013 Autocomplete textboxes using the term store and CSOM

CoreyRoth — Tue, 30 Apr 2013 15:30:00 GMT

I wanted to create an autocomplete textbox in a SharePoint app recently by using terms from the term store. Since retrieving items from the term store can be a bit involved I wanted to show you the steps involved. This solution make use of jQuery UI Autocomplete. The code loads the terms from the term store and then sets the source. This implementation is really only ideal for a small amount of terms, but it’s enough to get you started.

For this example, I am going to use a simple set of terms using state names in the United States. My terms are included in a group named Classification and a Term Set named States. Here is what my term store looks like.

In this example, we’re going to build our code inside a Client Web Part. Take a look at that post if you are not familiar with the process yet. We then need to add a heap of JavaScript references. Some of these are included already, but specifically we need to load SP.Taxonomy.js. We also need to include init.js as I mentioned in an earlier blog post.

<script type="text/javascript" src="../Scripts/jquery-1.7.1.min.js"></script>
<script type="text/javascript" src="/_layouts/15/MicrosoftAjax.js"></script>
<script type="text/javascript" src="/_layouts/15/init.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.runtime.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.taxonomy.js"></script>

My web part is called AutocompleteWebPart.aspx so I am going to add a JavaScript file for my code called AutocompleteWebPart.js. We also need to include a reference to jQuery UI You’ll need to download this and include it in your project or pull it from a CDN.

<script type="text/javascript" src="../Scripts/AutocompleteWebPart.js"></script>
<script type="text/javascript" src="../Scripts/jquery-ui-1.9.1.custom.min.js"></script>

Lastly to use jQuery UI, you need to include it’s CSS file in the Content folder of your project.

<link rel="Stylesheet" type="text/css" href="../Content/jquery-ui-1.8.22.custom.css" />

Now, I am just going to add a textbox to the body of our page.

<body>
    <div>
        <input id="autocompleteTextBox" type="text" />
    </div>
</body>

The process for querying terms is involved. You first need to get a reference to the Taxonomy Session, followed by the Group, the Term Set, and finally you can iterate the terms. There are a lot of good examples out there but many of them take short cuts by using GUIDs for values for things like the group and term set. This works but is absolutely useless when you are writing proper code that can be deployed to any environment. You need to be able to reference these items by name, but unfortunately the API makes accessing anything in the term store by name difficult. It’s not impossible though, it just requires extra code and iteration. Let’s walk through our JavaScript example below with absolutely no hard-coded GUIDs.

We’ll start by adding some global variables. We’ll populate these as we go.

var context;
 
var session;
var termStore;
var groups;
var termSets;
var termsArray = [];

We’ll start in a document ready function. We use the standard code to get a reference to the current context. We’ll need this to create a new TaxonomySession object. We then session.GetDefaultSiteCollectionTermStore() to get the default term store. From there, we need to context.load on the session and termStore objects. We then use a typical executeQueryAsync method to execute our query. The onTaxonomySession method will handle success and we’ll use a shared onTaxonomyFailed method to handle any failures.

$(document).ready(
    function () {
        context = new SP.ClientContext.get_current();
 
        session = SP.Taxonomy.TaxonomySession.getTaxonomySession(context);
        termStore = session.getDefaultSiteCollectionTermStore();
        context.load(session);
        context.load(termStore);
        context.executeQueryAsync(onTaxonomySession, onTaxonomyFailed);
    });

Just like with the managed API, you must configure your Managed Metadata Service Application Client appropriately in order for the default term store call to work. Click on the Managed Metadata Service Connection and then click Properties. Now, make sure the checkbox next to This service application is the default storage location for column specific term sets is checked. Once, you have made this change your code should work.

The onTaxonomySession method then retrieves a list of groups. We have to retrieve all groups because there isn’t a method to just retrieve one by name. Although there is a method to retrieve a group by id. Since we don’t want to hard code any GUIDs though. We have to retrieve all groups and iterate them to find the one we want. A successful query will call onGroupsLoaded.

function onTaxonomySession() {
    groups = termStore.get_groups();
    context.load(groups);
    context.executeQueryAsync(onGroupsLoaded, onTaxonomyFailed);
}

In this method we have a list of the groups so we need to iterate through them and find the one we want. In this case, Classification. The code isn’t ideal but it works. We start by getting an enumerator with getEnumerator(). We then use this enumerator to examine the groups. In our loop, we use get_current() to get currentGroup. We then use get_name() to compare against the one we want. When a match is found, we call another method getTermSets and pass the term set.

function onGroupsLoaded() {
    // iterate termStores
    var groupEnumerator = groups.getEnumerator();
 
    while (groupEnumerator.moveNext()) {
        var currentGroup = groupEnumerator.get_current();
        if (currentGroup.get_name() == 'Classification')
            getTermSets(currentGroup);
    }
}

In the getTermSets method, we call get_termSets.

function getTermSets(currentGroup) {
    termSets = currentGroup.get_termSets();
    context.load(termSets);
    context.executeQueryAsync(onTermSetsLoaded, onTaxonomyFailed);
}

The onTermSetLoaded method will then iterate through the term sets returned and compare by name in the same way. In this case, we are looking for the term set named States. When the match is found, we call getTerms().

function onTermSetsLoaded() {
    var termSetEnumerator = termSets.getEnumerator();
 
    while (termSetEnumerator.moveNext()) {
        var currentTermSet = termSetEnumerator.get_current();
        var termSetName = currentTermSet.get_name();
        if (termSetName == 'States')
            getTerms(currentTermSet);
    }
}

This is now the last call we need to make. This retrieves all of the terms for the term set. Unfortunately, we have to get all of them (as far as I know) which is why I don’t recommend this with large term sets.

function getTerms(termSet) {
    terms = termSet.get_terms();
    context.load(terms);
    context.executeQueryAsync(onTermsLoaded, onTaxonomyFailed);
}

The onTermsLoaded method will iterate through the terms and add them to an array that the jQuery UI autocomplete method will accept. There you have it all of the code to get items from a term set without a hard coded GUID. It’s a lot of code, but not too bad once you get used to it.

Lastly, we’ll get a reference to our textbox and use the .autocomplete() method passing in the value of our array.

function onTermsLoaded() {
    var termsEnumerator = terms.getEnumerator();
 
    while (termsEnumerator.moveNext()) {
        var currentTerm = termsEnumerator.get_current();
        termsArray.push(currentTerm.get_name());
    }
 
    $("#autocompleteTextBox").autocomplete({ source: termsArray });
}

At this point, we are done, but we do need to implement our failure method.

function onTaxonomyFailed(sender, args) {
    alert('Taxonomy Error:' + args.get_message());
}

If you are using this code in an app, the last thing you need to do is set the Taxonomy permission to Read in the AppManifest.xml file. This will let us query the term store.

At this point, we can test it. Deploy your app and add the app part to a page.

So, a little code involved here but the results are great. You can configure the jQuery autocomplete plugin in a variety of ways too. This code could probably be optimized some so if you have improvements, let me know.

JavaScript runtime error: 'NotifyScriptLoadedAndExecuteWaitingJobs' is undefined

CoreyRoth — Tue, 30 Apr 2013 02:57:58 GMT

I recently ran into the following error when working with a SharePoint 2013 Client Web Part (App Part) while accessing the term store using SP.Taxonomy.js.

JavaScript runtime error: 'NotifyScriptLoadedAndExecuteWaitingJobs' is undefined.

The following line gets hit in the debugger.

The code I had worked fine inside a page, but when placed inside a client web part, I received the error. I thought it might be something to do with the order in how I loaded the script files. I recently switched to the new Client Web Parts set up in the RTM version of the Office Developer Tools. This particular update changes the references to the JavaScript files to the page instead of being loaded dynamically with $.GetScript(). It turns out it had nothing to do with that. Instead, I just needed to add a reference to Init.js. Here is what my complete list of references looks like in the page for my client web part.

<script type="text/javascript" src="../Scripts/jquery-1.7.1.min.js"></script>
<script type="text/javascript" src="/_layouts/15/MicrosoftAjax.js"></script>
<script type="text/javascript" src="/_layouts/15/init.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.runtime.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.taxonomy.js"></script>

If you receive the error above that is all you have to do.. Luckily, it’s easy to fix.

How to: Query Search with the SharePoint 2013 JavaScript Client Object Model

CoreyRoth — Fri, 19 Apr 2013 03:08:32 GMT

As a developer, if you have ever looked for information on how to query search in SharePoint, there is a good chance that you have ran into one of my articles. I’ve been writing about how to query search in a variety of different ways since 2007. They have always been some of the most popular articles on my site. SharePoint 2013 has so many new ways to query search, it has taken me time to write up all of the different ways. I am keeping the tradition alive by writing about how to query using the JavaScript Client Object Model provided by SP.Search.js. You may have already seen my post on how to query from JavaScript and REST or my post on how to use the managed CSOM to Query Search. You’ll find that querying from JavaScript looks very similar to the managed side of things. In fact even the namespaces are the same and most of the code is quite similar between C# and JavaScript. However, there are some nuances due to JavaScript so I wanted to share a complete code sample.

I am going to build my example inside a SharePoint-hosted app. If you’re not familiar with that process yet, take a look at my Client Web Part post to get started. When it comes to apps, you need to be sure and request permission to access search. Do this by editing your AppManifest.xml and clicking on the permissions tab. Select Search and then select QueryAsUserIgnoreAppPrincipal. If you forget this step, you won’t get an error, your queries will simply just return zero results.

I’m going to put all of my code in the welcome page today. My default.aspx page will have the same HTML as my other JavaScript post. I simply add a textbox, a button, and a div to hold the results. The user will type in his or her query, click the button, and then see search results.

<div>

<label for="searchTextBox">Search: </label>

</div>

</div>

We’re going to edit App.js next. Since we’re in an App, I am assuming you already have code to get the SharePoint context since Visual Studio adds it for you. If not, you can get it like this.

var context = SP.ClientContext.get_current();

I then add a click event handler to my document ready function.

$("#searchButton").click(function () {
});

In here, we’ll put our code to get a KeywordQuery and SearchExecutor object to execute our query in a similar manner to the Managed CSOM approach. Now, we need to get our KeywordQuery object using the context object we already have.

var keywordQuery = new Microsoft.SharePoint.Client.Search.Query.KeywordQuery(context);

Then, we set the query text using the value the user entered in the textbox with set_queryText().

keywordQuery.set_queryText($("#searchTextBox").val());

Now, we just need to create a SearchExecutor object and execute the query. I am assigning the results of the query back to a global variable called results. Since apps by default have ‘use strict’ enabled, you need to be sure and declare this first.

var searchExecutor = new Microsoft.SharePoint.Client.Search.Query.SearchExecutor(context);
results = searchExecutor.executeQuery(keywordQuery);

Then like any CSOM code, we have to use executeQueryAsync to make the actual call to the server. I pass it methods for success and failure.

context.executeQueryAsync(onQuerySuccess, onQueryError);

I generally prefer using REST to do my search queries. However, when it comes to processing results, the data we get back from CSOM is typed better and much easier to access. This results in less code that we have to deal with. You can get quite a bit of data back such as the number of results returned just by exmaining results.m_value. Each individual result can be found in results.m_value.ResultTables[0].ResultRows. The managed properties of each row are typed directly on the object so that it means you can access them directly if you know the name (i.e.: Author, Write, etc). Iterating the values is simple using $.each. Take a look at my example where I am writing the values into an HTML table.

function onQuerySuccess() {
    $("#resultsDiv").append('<table>');
 
    $.each(results.m_value.ResultTables[0].ResultRows, function () {
        $("#resultsDiv").append('<tr>');
        $("#resultsDiv").append('<td>' + this.Title + '</td>');
        $("#resultsDiv").append('<td>' + this.Path + '</td>');
        $("#resultsDiv").append('<td>' + this.Author + '</td>');
        $("#resultsDiv").append('<td>' + this.Write + '</td>');
        $("#resultsDiv").append('</tr>');
    });
 
    $("#resultsDiv").append('</table>');
}

The last thing to implement is the code to handle errors. It just sends the error to an alert dialog.

function onQueryFail(sender, args) {
    alert('Query failed. Error:' + args.get_message());
}

When we run the app, it will look something like this.

Executing a query will show us the four columns I specified in my $.each statement.

Pretty easy, right? Here is the entire code snippet of my App.js.

'use strict';
 
var results;
 
var context = SP.ClientContext.get_current();
var user = context.get_web().get_currentUser();
 
// This code runs when the DOM is ready and creates a context object which is needed to use the SharePoint object model
$(document).ready(function () {
 
    $("#searchButton").click(function () {
        var keywordQuery = new Microsoft.SharePoint.Client.Search.Query.KeywordQuery(context);
        keywordQuery.set_queryText($("#searchTextBox").val());
 
        var searchExecutor = new Microsoft.SharePoint.Client.Search.Query.SearchExecutor(context);
        results = searchExecutor.executeQuery(keywordQuery);
 
        context.executeQueryAsync(onQuerySuccess, onQueryFail)
    });
});
 
 
function onQuerySuccess() {
    $("#resultsDiv").append('<table>');
 
    $.each(results.m_value.ResultTables[0].ResultRows, function () {
        $("#resultsDiv").append('<tr>');
        $("#resultsDiv").append('<td>' + this.Title + '</td>');
        $("#resultsDiv").append('<td>' + this.Author + '</td>');
        $("#resultsDiv").append('<td>' + this.Write + '</td>');
        $("#resultsDiv").append('<td>' + this.Path + '</td>');
        $("#resultsDiv").append('</tr>');
    });
 
    $("#resultsDiv").append('</table>');
}
 
function onQueryFail(sender, args) {
    alert('Query failed. Error:' + args.get_message());
}

Although, I typically prefer the REST interface for querying search. I have to admit, I like the ease of working with the results in CSOM. Hopefully, you find this sample useful. Thanks!

I’ve also uploaded the full Visual Studio solution to MSDN Code Samples.

Speaking at SharePoint Saturday Houston, San Antonio SharePoint Users Group, and SharePoint Summit Toronto

CoreyRoth — Wed, 10 Apr 2013 18:54:51 GMT

I’ve got a number of talks coming up that I am excited about. It turns out that talking about my experiences publishing SharePoint 2013 apps to the Office Store is hot! I’ve already spoken about it in Austin and now I’ll be speaking about it at the following events:

SharePoint Saturday Houston (4/13)
San Antonio SharePoint Users Group (4/26)
Dallas Fort Worth Users Group (6/18)

If you’re in a major city in Texas and want to hear about apps, I’ve got you covered! This talk covers my personal experiences building a business around selling apps in the Office Store. The talk is mostly non-technical and covers more of the details around what you need to submit and publish an app. If you’re going to be at any of the events be sure and check it out.

I’m also giving a talk about the various aspects of the Search API in SharePoint 2013 at SharePoint Summit Toronto (5/13 – 5/15). If you’re going to be in the area, be sure and check it out!

Follow me on twitter: @coreyroth.

How to: Build Client Web Parts in SharePoint 2013 with Office Developer Tools RTM

CoreyRoth — Tue, 09 Apr 2013 20:37:44 GMT

This is the third time (and hopefully final) I am writing this post about building Client Web Parts (App Parts) for SharePoint 2013 with Visual Studio 2012. This is largely due to the Office Developer Tools going through a few iterations (Preview 1 and Preview 2). I don’t want to leave out-dated information out there, so here is the updated version. The process remains largely the same, but a few of the screens have changed and what Visual Studio produces for us has changed significantly since Preview 1.

When you create the project, the first two steps look pretty much the same as Preview 1 and Preview 2.

The next step looks the same as well. For our example, we’ll go with a SharePoint-hosted app again.

The good news is, in Preview 2 they’ve added a wizard that helps you get stared with client web parts. This wizard does three things for you. It creates an application page for the client web part, it add it to elements.xml, and it registers the CSS files from SharePoint so that the content inside the IFRAME is styled appropriately. They have also added all of the required JavaScript files you need. I’ll talk about those more in a second. Once you have created the project, add a new item, and choose Client Web Part (Host Web).

You’ll notice on the list that there is a new entry for Search Configuration as well. I talked about that last week in a previous post. When you go to the next step, you get a new dialog in the wizard that gives you the option to create a new page for the client web part. This dialog has been updated slightly since Preview 2.

When you complete the wizard, it will generate quite a bit of HTML and JavaScript including all of the script files needed to get started referencing SharePoint. Let me post the whole code snippet, so you can see what I mean.

<%@ Page language="C#" Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ 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" %>
 
<WebPartPages:AllowFraming ID="AllowFraming" runat="server" />
 
<html>
<head>
    <title></title>
 
    <script type="text/javascript" src="../Scripts/jquery-1.7.1.min.js"></script>
    <script type="text/javascript" src="/_layouts/15/MicrosoftAjax.js"></script>
    <script type="text/javascript" src="/_layouts/15/sp.runtime.js"></script>
    <script type="text/javascript" src="/_layouts/15/sp.js"></script>
 
    <script type="text/javascript">
        'use strict';
 
        // Set the style of the client web part page to be consistent with the host web.
        (function () {
            var hostUrl = '';
            if (document.URL.indexOf('?') != -1) {
                var params = document.URL.split('?')[1].split('&');
                for (var i = 0; i < params.length; i++) {
                    var p = decodeURIComponent(params[i]);
                    if (/^SPHostUrl=/i.test(p)) {
                        hostUrl = p.split('=')[1];
                        document.write('<link rel="stylesheet" href="' + hostUrl + '/_layouts/15/defaultcss.ashx" />');
                        break;
                    }
                }
            }
            if (hostUrl == '') {
                document.write('<link rel="stylesheet" href="/_layouts/15/1033/styles/themable/corev15.css" />');
            }
        })();
    </script>
</head>
<body>
</body>
</html>

The above code differs from Preview 2 in that it also includes references to MicrosoftAjax.js, sp.runtime.js and sp.js. Why we never bothered to include scripts this way in the past is beyond me. In the past, we used $.getScript to dynamically load the SharePoint scripts. That’s way over complicated when you can just get it out of the layouts directory.

At this point, I recommend adding another script file to your project. I tend to go with one script per client web part. You can put all of your script code in there. At this point, you’re also ready to deploy the client web part and try it out. Deploy, your project, click on the Developer Site link, and then edit the page. Click App Part and then choose your newly deployed client web part.

That should get your started. On a related note, the JavaScript code also changed slightly in App.js (the script file for your default.aspx page). Here’s what it looks like if you’re curious.

The new tools make it much easier to get started with Client Web Parts, so be sure and get them if you haven’t already. Also take a look at my Preview 1 and Preview 2 posts as they can walk you through some of the other steps.

How to: Query SharePoint 2013 using REST and JavaScript

CoreyRoth — Tue, 09 Apr 2013 19:15:40 GMT

I have a session coming up at SharePoint Summit Toronto this year about the many different ways you can query search. Whenever I am working on a new talk, it is customary for me to write blog posts about my examples so here it is. :) I first learned how to query SharePoint 2013 search with the new REST API and JavaScript from looking at examples from @ScotHillier on MSDN. However, the last time I tried the example, I noticed an issue which I equate to most likely a change between beta and RTM. This post shows you my version of how to query search using the REST API and JavaScript.

For this post, I am using the RTM Office Developer tools (which I have a post coming out on soon). I am going to use a SharePoint-hosted app for my example but you could also use this in a web part with farm solution as well. When it comes to apps, you need to be sure and request permission to access search. Do this by editing your AppManifest.xml and clicking on the permissions tab. Select Search and then select QueryAsUserIgnoreAppPrincipal. If you forget this step, you won’t get an error, your queries will simply just return zero results.

For my example, I am just going to add my code to the default.aspx page in the app. I simply add a textbox, a button, and a div to hold the results. The user will type in his or her query, click the button, and then see search results. You could put this in a Client Web Part if you wanted.

<div>
    <label for="searchTextBox">Search: </label>
    <input id="searchTextBox" type="text" />
    <input id="searchButton" type="button" value="Search" />
</div>
 
<div id="resultsDiv">
</div>

Now, we need to add the necessary code to App.js. I start by removing the example code that retrieves the user information. I instead, add a click handler to my searchButton to execute the search query. If you remember from my previous post on REST, we assemble a URL by appending /api/search/query to a SharePoint host URL. For example.

http://server/_api/search/query

However, in an app, we have to request the URL to the App. One way to do this is by query string using the SPAppWebUrl parameter. SharePoint passes this parameter to your app start page automatically. We can request it with a line line this. Remember getQueryStringParameter() is a helper method that we have gotten from some of the SharePoint examples. I’ll include it in the full code listing at the bottom of this post.

var

spAppWebUrl = decodeURIComponent(getQueryStringParameter('SPAppWebUrl'));

To pass the user’s query to SharePoint, we need to include the querytext parameter on the REST URL. Be sure to enclose the value in single quotes. Again more details in my previous post.

http://server/_api/search/query?querytext=’SharePoint’

Now, we need to create a click handler for the search button, build the URL, and then execute the query.

"#searchButton").click(function () {

});

Inside the click handler, assemble the URL, using the concatenation of the spAppWebUrl, /api/search/query, and the querytext parameter. The value of querytext will be retrieved from the textbox we added earlier.

var queryUrl = spAppWebUrl + "/_api/search/query?querytext='" + $("#searchTextBox").val() + "'";

Now, we just execute the query with $.ajax(). Pass the queryUrl in the url parameter. This example uses the GET method but if you have a lot of parameters, you may consider using POST instead. Lastly, this part is key to get this example to work. The accept header must have value of "application/json; odata=verbose". The odata=verbose part is not in the MSDN example. If you leave it out, you will receive an error. The last parameters are the methods that will handle the success and failure of the AJAX call. Here’s what the whole method looks like.

$("#searchButton").click(function () {
    var queryUrl = spAppWebUrl + "/_api/search/query?querytext='" + $("#searchTextBox").val() + "'";
 
    $.ajax({ url: queryUrl, method: "GET", headers: { "Accept": "application/json; odata=verbose" }, success: onQuerySuccess, error: onQueryError });
});

Now, you need to write code to handle the success. The results come back in JSON format, but unfortunately, they are buried in a hugely nested structure. Each individual result can be found in data.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results. Your best bet is to assign this a variable and then use a template or manually parse it. In my example, I am just going to use $.each to iterate through the results using brute force. The individual columns of each search result can be found in this.Cells.results.Value. Ok, that’s confusing I am sure, so let’s look at the code and then step through it. I’m just writing out a simple table by appending HTML tags to a div.

function onQuerySuccess(data) {
    var results = data.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results;
 
    $("#resultsDiv").append('<table>');
 
    $.each(results, function () {
        $("#resultsDiv").append('<tr>');
        $.each(this.Cells.results, function () {
            $("#resultsDiv").append('<td>' + this.Value + '</td>');
        });
        $("#resultsDiv").append('</tr>');
    });
 
    $("#resultsDiv").append('</table>');
}

Effectively, I have two nested loops. One to iterate through each result and one for each managed property (column) in the results. When you get inside the Cell, this.Value will show the value of the result while this.Key will contain the name of the managed property.

The last thing to implement is the code to handle errors. It’s relatively simple and just writes error.StatusText to the div.

function onQueryError(error) {
    $("#resultsDiv").append(error.statusText)
}

When I run my app, here is what it looks like.

Executing a query in the app, gives us results but they aren’t pretty. You can pretty them up yourself. :) It also doesn’t include anything to print out the managed property names on the table. You could get the names by looking at each cell of the first result and using this.Value.

You can see, it’s really pretty easy to get started. You can further refine your REST query to request specific fields, sort orders, and more. I’ll probably write a follow-up post in the future to include some of those details. Here’s the whole source code for my example that you can work with.

var context = SP.ClientContext.get_current();
 
// This code runs when the DOM is ready and creates a context object which is needed to use the SharePoint object model
$(document).ready(function () {
 
    var spAppWebUrl = decodeURIComponent(getQueryStringParameter('SPAppWebUrl'));
 
    $("#searchButton").click(function () {
        var queryUrl = spAppWebUrl + "/_api/search/query?querytext='" + $("#searchTextBox").val() + "'";
 
        $.ajax({ url: queryUrl, method: "GET", headers: { "Accept": "application/json; odata=verbose" }, success: onQuerySuccess, error: onQueryError });
    });
 
});
 
function onQuerySuccess(data) {
    var results = data.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results;
 
    $("#resultsDiv").append('<table>');
 
    $.each(results, function () {
        $("#resultsDiv").append('<tr>');
        $.each(this.Cells.results, function () {
            $("#resultsDiv").append('<td>' + this.Value + '</td>');
        });
        $("#resultsDiv").append('</tr>');
    });
 
    $("#resultsDiv").append('</table>');
}
 
function onQueryError(error) {
    $("#resultsDiv").append(error.statusText)
}
 
//function to get a parameter value by a specific key
function getQueryStringParameter(urlParameterKey) {
    var params = document.URL.split('?')[1].split('&');
    var strParams = '';
    for (var i = 0; i < params.length; i = i + 1) {
        var singleParam = params[i].split('=');
        if (singleParam[0] == urlParameterKey)
            return decodeURIComponent(singleParam[1]);
    }
}

That’s all there is to it. Hopefully, you find this example useful. Thanks.

The complete Visual Studio for this code snipped has also been uploaded to MSDN Code Samples.

Importing Search Configurations with SharePoint Apps

CoreyRoth — Wed, 03 Apr 2013 16:21:44 GMT

The Office Developer Tools team snuck a new feature into the RTM version of the tools for Visual Studio 2012. This new feature allows you to deploy apps and actually alter the search schema on the host web. That’s right. You can deploy an app and it will directly change the search configuration on the host. They just released documentation on it a while back, but as usual, I wanted to share my experiences. That and I know you all like screenshots.

What does this feature actually do? Well let’s back up a bit. If you remember back from my post, Search is Everywhere, I mentioned the we now had the ability to export and import search settings. This works at the SSA, site collection, and site level and allows you to move everything from result sources to managed properties from one environment to another. This is big as it lets you finally promote search settings between environments and maintain a true SDLC when it comes to search. Why do we care about search configuration with apps? Well this allows the developer to package up search settings in Visual Studio 2012 and then move them to production without having to do manual steps or use PowerShell. This also means you could include search settings in an app that you would put in the Office Store. It certainly opens up possibilities.

To test this out, go to your source site collection and customize your search settings. In my example, I created a custom result source and some managed properties on our source site. In my example, I actually did this on an on-premises installation of SharePoint 2013.

This particular result source does nothing exciting. It simply limits the search to documents, but it serves as a good example. I’ve also created a managed property mapped to the Author crawled property. You may already know about this part, but I am showing it for a reason.

Now, I am going to export my search settings of my site collection, by going to Site Settings –> Search –> Configuration Export.

At this point, I could manually import the search settings using Configuration Import on another site collection. However, we want to do this from an app. Let’s get started in Visual Studio 2012. Start by creating a new SharePoint-hosted app. Once it is created, add an item to the project and choose Search Configuration.

The next step will ask for the path to your configuration XML file that you exported.

At this point the process is done. It will show you an XML editor with the contents of your search configuration. According to the MSDN documentation, you then need to edit it and set the DeployToParent element to true.

We then need to grant permissions to access the Site Collection. To do this, open AppManifest.xml and then click on Permissions. On this tab, add a scope of Site Collection and set the value to Full Control.

At this point, we are are ready to deploy. In my example, I am taking my search configuration and deploying it to an Office 365 SharePoint Online tenant. When the app deployment completes, you’ll be prompted if you want to trust the app. Trust it and then you should see your app start page.

At this point, you are just going to see you default app start page. There is nothing visible in the application. Go to the Developer Site (or the site collection you deployed to) and go to the Site Settings. Then look at the Result Sources. If everything worked correctly, you should now see your new result source there.

It was successfully deployed. Now what about the managed property? Unfortunately, it is no where to be found. If you go back to Visual Studio and look at your XML, you’ll notice that your managed property definition is no where to be found there either. If you check the source file before you imported it though, you’ll see the definition. After I noticed this particular behavior, I reached out on Twitter and @chakkaradeep reached out to me and told me that managed properties aren’t supported in this deployment model. That made me kind of sad because that’s what I want to deploy the most. I’m sure there is a technical reason though that he’ll explain to me sometime though. You can still deploy managed properties via Configuration Import though which is still a great added feature of SharePoint 2013.

You might be curious if the result source is removed when you uninstall the app. It turns out that the changes are indeed removed when you uninstall.

Aside from the managed properties not being available, this is still a pretty cool feature and it has me thinking about some new things I can do that I didn’t think were possible before. I’m pretty excited to work with it more.

Judging an IT department’s effectiveness by how long it takes to create a user account

CoreyRoth — Tue, 02 Apr 2013 17:03:59 GMT

As an IT consultant, I have seen it all (ok that’s a pretty big statement…I have seen a lot). I often ask why does it take days, weeks, or even months to create a new user account? Is it because there is so much process involved, your help desk or administrators are over-worked, or is it because someone in the chain is slacking? Honestly, it could be any of this. I find that watching how long it takes to create a user account is a good metric for an IT department’s efficiency. You can see things from a business process and technical perspective by watching this process. It shows how well the business process works to request and approve an account. It can also expose any resourcing shortfalls that you may have. In reality, the process of creating a new user account should really be simple. Read more to look at possible causes of why it takes so long to create user accounts and for ways to improve it.

If you’re reading this as a business user or executive and have been told the process of physically creating the account takes forever, prepare to get angry. Watch this video and see how long the process actually takes. This particular video (albeit old) is under two minutes and there is a lot of ramp up time. The process takes seconds. I’ll give you that it might take a big longer if you are also configuring Exchange mailboxes (although minimal) or trying to decide on a username, but as you can see the process doesn’t take that long. If your administrator tells you that this process takes a long time, he or she is lying and it’s time for him or her to go.

Let’s look at the business process. Obviously, you need to have some sort of approval process for creating accounts. Your data is important. You don’t want people requesting accounts for their friends or even worse a competitor. Who needs to approve an account request? Well from what I have seen in the past, typically someone from the business approves the request such as the requester’s manager, director, or VP. You’ll probably also have someone from the IT department approve it as well. Every organization is different, but if you have more than two or three approvals required to create an account, that is probably over-kill. You definitely don’t want to have too many VP-level or C-level approvals required. After all, most of them don’t really care nor do they have time to deal with your approval to begin with.

For each approval you have, you can pretty much assume that is going to cost you a day at least. A well-engineered process will use multiple approvers and have fall-backs for when approvers are not available. It should also have task reminders to remind approvers to approve tasks after a set period of time. What is not surprising is that the technology that powers this process widely varies in every organization and it is far from standardized. Typically, organizations manage this process inside their help-desk ticketing system. I’ve also seen it put together in everything from an E-mail, a custom form, a Word document, you name it. You could certainly build an approval workflow in SharePoint too. :) If it takes a long time to create a user account though, it is more than likely a business process problem and not a technology problem.

It’s amazing how much money is lost because a new hire or contractor doesn’t have an account. I see it all the time. If I was the CFO, I would be yelling at you the CIO to get this process under control. Of course, no one in their right mind would let me manage a company’s money. :) Creating a user account should not take weeks and you know it. So as the leader of an IT department, how do you fix it? You need to figure out if it is a technology problem, a resource problem, or an approval problem.

Although I have never seen a help desk system that I would classify as great, I would rarely say it is a technology problem. Still though, you can look at the process that the end user completes to get an account created. This could be a form, an E-mail, logging in to the help desk system, or a phone call. Make sure the process is obvious and make sure your users know how to get to it.

Let’s look at potential resource problems. Monitor how long the ticket sits with the person actually creating the user account as well as the number of other tickets. If that administrator is being hit with 50 new tickets a day and he or she can’t keep up, then it’s probably a resource problem which ultimately means it’s your fault. Get that poor admin some help. If the administrator only has a handful of tickets a day and doesn’t have any other responsibilities, you may be dealing with a slacker and you need to fix the problem. Slackers are notoriously bad about making up excuses of why things take so long. They use your ignorance in technology against you because as a non-techie you no means to question them. Ask the slacker lots of questions and it usually becomes pretty obvious.

You can find approval problems by looking at ticket history and examining the time in between approvals. If you are seeing huge lags times in between approvers, you likely have too many required approvers or the wrong approvers. Look and see if you see any trends where the process is getting hung up. Interview people from your help desk about it because chances are one of them knows where the delays usually come from. Think back to when the approval process was first created, does anyone there even remember why it was built the way it was? Don’t be afraid to re-engineer the process from the beginning to simplify it. Does the CIO or the VP of Legal really need to approve every account? I’ve seen it before and it just really isn’t necessary. Put a little more trust in your management to make the right decisions. After all you hired them because they are good people and they just want to get work done.

Lastly, separate the account creation process from the process to grant permissions to applications and files. If the user is going to need access to sensitive files, often times you will want additional approvals. Separate this from the account creation process so that the new employee can at least read E-mail and get started with his or her job. Let the approvals for those sensitive areas come in on a separate ticket to expedite the process.

I know there could be other factors in the mix such as dependencies on HRMS systems and the like. What have you seen? I know a lot of you out there are consultants and work with companies of varying sizes. What are your experiences? Do you have any good stories about starting somewhere? Share them in your comments.

I could be totally off base here. I haven’t done any significant systems administration work in years, but I think these are good ideas. As part of being a SharePoint architect, I am often working with business users to improve processes and this one almost always needs help. Remember, nothing gives your IT department a worse name than being slow at executing such a rather simple process. Perception is reality. Fix this problem in your organization and you’ll get a big win with your stakeholders.

Configuring and using IRM with Office 365 and SharePoint Online

CoreyRoth — Thu, 28 Mar 2013 21:34:16 GMT

I’ve always founds IRM quite fascinating and the nice thing about Office 365 is that it is really easy to configure and use. There are a few steps involved, but I managed to figure them out without having to go read a heap of documentation. I thought I would share my experience here today so you know what’s possible. This assumes you are on a new Office 365 tenant or one that has been upgraded already (not that any of mine have been. :) ). I know this is only available in certain plans and I need to double-check which ones, but I haven’t had a chance yet. If you set up a trial from MicrosoftOfficeDemos.com, you can definitely try it with that account.

To configure IRM, it requires you turn it on in two places: in the Office 365 Portal and in SharePoint Online tenant administration. Let’s start by going to the Office 365 Portal. You can get there by clicking on Admin –> Office 365 at the top. Then click on Service Settings –> Rights Management. Rights Management is disabled by default, so you need to activate it.

On this screen simply click Manage and you will be taken to the Windows Azure Directory Rights Management site (notice the URL changes). From here, you can start the activation process.

Click the Activate button and you’ll be taken to a screen to confirm.

Click the Activate button again and the process gets started.

Now, you need to go your SharePoint tenant administration to activate it there. Click on Admin –> SharePoint and then Settings. In the middle of the page, look for the Information Rights Management (IRM) section and check Use the IRM service specified in your configuration. Then click Refresh IRM Settings. Now, it takes a few minutes for your activation to take effect in the Office 365 Portal so if you click on this too early, you are likely to see the following error.

Error: RMS Online is configured for this tenant but is turned off, please turn on in Office 365 to enable.

Keep trying and after a few minutes, it should activate. Be sure and click Save when you are done.

At this point, you can actually try things out inside office. I’m working off of the demo sites that I mentioned earlier. Now, one thing to point out is that Office uses whatever account you are signed in with to determine which Rights Management Server to connect to. Therefore, if you are using a test Office 365 account, you need to actually, log into Office with that account. Simply click on your name in the top right and click Switch Account. If you don’t do this, it may time out or try to connect to another RMS server like the one at your company.

To try things out, open up a document on your SharePoint server, click File and then click Protect Document and then Restrict Access. The first time you choose this, there is an option to connect to rights management services. Once it connects, you’ll see options on protecting the document. We’re going to go with Restricted Access.

On the next screen, you will be prompted to assign who can view the document or edit the document. In my example, I am going to grant read permission to Sara Davis. I simply typed in her full Office 365 Id. This means she will be able to open the document and view it, but cannot save or print it.

If you click on More Options, you’ll get a window where you can set even more granular permissions such as expiring the document, allowing printing, as well as an E-mail address that gets used to request additional permissions.

Once we are finished, save the document back to SharePoint. Now, when Sara opens the document, she is going to get a different experience. To test using the document with Sara, I have to sign in to SharePoint with her account. I also have to open Office and sign out with Garth and sign in with Sara’s account. Here’s what it looks like.

Office informs me that access is restricted and if I click View Permission, it will show me what I am allowed to do. Notice I can only view the document. If I try to access the document with a user who does not have access granted through IRM, Office tells me I can’t open the document like this.

When a document is protected with IRM, Office Web Apps will be unable to show a preview of the document’s contents. Here’s what it looks like when that happens.

I really like how easy it is to get started with IRM in Office 365. If you have an interest in this feature, check it out today. It’s definitely much easier to get started with it here than it is on-premises.

Determining the most popular items in a document library in SharePoint 2013

CoreyRoth — Thu, 28 Mar 2013 19:39:39 GMT

With the combination of analytics and search in SharePoint 2013, there is a heap of new features to help determine which content is actually being used. No longer is this information buried in reports for administrators, but it in fact is available right from the ribbon in a document library. Maybe you have even noticed the Most Popular Items button in the ribbon already. You can find it on the library tab in the middle.

Click on it and you will be taken to a custom search results screen that shows you recent views and total views.

What’s nice is that you can even search and refine within the report if you are looking for something specific. You can also click on the Popularity Trends link to get a nice graph of the usage of the file over time.

Behind the scenes, this report is powered by the Popular result source. You can also use this source to look for popular items across your entire index. As a developer, the possibilities are quite interesting.

My particular tenant doesn’t have a ton of usage, but if you’re already running SharePoint 2013 you might be able to extract some valuable insights from this report. Try it out today.

Microsoft Partner Benefits: Rocking your SharePoint Online demos

CoreyRoth — Fri, 15 Mar 2013 15:51:11 GMT

If you haven’t heard, Microsoft released a new site recently that allows you to create a new Office 365 tenant that is pre-populated with users, content, and social data. It even comes with demo scripts that you can use to walk users through the new features of SharePoint Online. What’s the catch? Your Windows Live ID must be affiliated with a Microsoft Partner and you need to have plenty of time to wait for it to provision. It typically takes between 8 and 36 hours for the provisioning process to complete. Tenants are created in trial mode and you have 30 days that you can use it for free. After that, you can either pay for licenses or simply request a new tenant. This isn’t necessarily a bad thing, because the sample social data expires after 14 days. If you want to demonstrate social, it’s really just easier to get a new tenant.

Even if you work for a partner and a lot of you out there do, I found that a lot of people aren’t affiliated with their company’s partner Id. So if you click on the Microsoft Partner link and it gives you an error, you need to affiliate yourself with your company’s partnership. I’ve given a few colleagues this link to associate themselves and it appears to have worked for them. Let me know if you have an issue with it.

When you are ready to create a new tenant, go to the Create Demo page. This page is a bit confusing because all of the options are disabled. Just click Create Your Demo to proceed.

On this page, you specify your region, tenant name, and E-mail address. You’ll get an E-mail when the process completes with the URL and login information.

After you fill in your information, click Create My Account and start waiting. This is an excellent time to review some of the demo scripts out there. Click the Resources link at the top and you’ll see demo scripts broken up by product. This is also an excellent time to go ahead and stop reading this article and get your tenant provisioning. You can come back and read more once you get it started. :)

When the process completes, you will receive an e-mail with the login and password. Click on that link to begin exploring. However, for most of the demos they recommend a demo user, Garth Fort. The login for this user will be garthf@tenantname.onmicrosoft.com. The password should be the same for all accounts pass@word1. Keep that in mind. You may want to change the default passwords of your accounts. If you look at the users section, you will see a number of user accounts have been created for you. It even includes things like conference rooms. These users have pictures and completed user profiles and even social data which we’ll see later.

I’m going to focus on SharePoint content, so click on the Admin link at the top and choose SharePoint. When you go to the SharePoint Online administration tenant, you’ll see that it creates a number of site collections.

Although it’s fairly obvious. Here’s a quick summary of what’s in the site collections.

Root (/) – Demo landing page. Links to the various site assets and demo scripts for SharePoint
/Search – Search Center
/sites/BICenter – Demos using Power View and Visio Services
/sites/Communities – fully populated community sites with discussion boards
/sites/Contoso – main Intranet site
/sites/ContosoBeta – no content
/sites/eDiscovery – discovery center
/sites/KnowledgeCenter – knowledge center with custom branding

What I like about these demos is that there is a lot of examples of what SharePoint can do and a lot of the features are really highlighted. I’ll take you through some of the pages so you have an idea of what you can expect. When you go to the root of your tenant, you’ll see a landing page with links to the demo home page, assets, and scripts.

A good starting place is the Demo Home Page.

Now is a great time to start exploring the site. What I like is a lot of the sites demonstrate out-of-the-box features. Take a look at the Engineering Department site. They have an example of showing reports with Power View using Excel Services.

If we look at the Sales and Marketing site, it has some nice examples of KPIs, the PowerPoint viewer as well as documents that have been rated.

If you’re looking to tell a story about BI, click on the Report Dashboard link on the left. There is a good example of a Power View sheet with filters and maps.

One of my favorite sections of the demo is the Communities section. It’s a great example of using social and shows off the gamification concepts quite well.

Going to one of the communities, you’ll see active discussion boards with top contributors.

You can view individual discussions to show how users interact with each other.

I think the social aspects are some of the best things to demo. If you click on the Newsfeed link, you’ll find quite a bit of activity. Just keep in mind this information will expire after two weeks so it’s good to keep a fresh tenant when you’re doing a demo.

In the screenshot above, you’ll see posts from users that Garth is following as well as various things the user has posted or followed. That video can be watched directly from the newsfeed too.

Clicking on one of the tags such as #CSAT will show you all of the posts that have used that particular hash tag.

There are good examples of the user being mentioned by other people as well.

Search demos extremely well with SharePoint Online because Office Web Apps is included and running.

When doing a demonstration, you can show the hover panel on search results with the preview of the document. I especially like showing users how you can jump directly to a specific section of a document. You’ll also notice how you can filter by Tags or Content Type.

The MOD demos also provide a working eDiscovery center, but I don’t think there is a link to it so you’ll have to type the URL in yourself. This is a great way to show examples of how SharePoint can place holds on SharePoint and Exchange content. If you look at one of the open cases (i.e.: CT77A11), you can define a discovery set. You’ll need to login as the admin account to do this.

If you look at the sources, you can see I have added a few Exchange mailboxes as well as a SharePoint site. Clicking on the Preview Results button will show you content from both Exchange and SharePoint based on the filters you provided.

Everything comes back in these results, so remember your mailbox can always be seen by someone. :)

The BI Center is pretty slick as well. Take a look at the Custom Satisfaction Dashboard. This is a great example of combining graphs with Power View and adding a social aspect that people can comment on.

The last thing I will point out is the Knowledge Center. Here is a great example of how they really changed the way content looks in SharePoint.

Of course, there is plenty of content out there for you to explore. If you can’t sell someone on the value of SharePoint with these demos, you’re doing something wrong. :) Get out there and try it out today (or tomorrow when it finishes provisioning). Here’s the link again for you to get started.

MicrosoftOfficeDemos.com

Installing SharePoint 2013 apps with PowerShell

CoreyRoth — Thu, 28 Feb 2013 17:00:00 GMT

My PowerShell posts always prove to be the most popular. I showed all sorts of cool PowerShell tricks in my talk back at SPC12. One of the things I covered was how to install and manage apps using PowerShell. Since there is a corporate catalog and SharePoint store, you might not think you need to install apps with PowerShell, but your developers may choose to the app model for a future internal project, so as an IT Pro you need to know how to install the thing. There are a lot of similarities to working with solution packages but there are several differences to be aware of. The documentation on TechNet is pretty good, but putting it all together can be tricky.

Specific to PowerShell, there is some terminology to familiarize yourself with. You’ll see these for parameter names so you need to know what they are otherwise you’ll find yourself confused.

App Package – physical file containing the app (.app file)
App – an instance of an app installed on a particular subsite

Along with the App, you’ll find an Id property that refers to a GUID of that particular app instance. We’ll talk about that more when it comes to updates.

To begin installing app, we first install the .app file into a site collection and then we deploy the app to an individual subsite. To install the app package, we use Import-SPAppPackage. Specify the path to your app package (.app file) with the –Path parameter. You’ll also need to specify which Site Collection will contain the app using the –Site parameter. Finally, the Source parameter tells SharePoint where the app came from (SharePoint Store, Corporate Catalog, or Object Model). I always specify a value of ObjectModel for my custom apps. Here’s what the command looks like. Assign the results of the command to variable so that you can use it in the next step.

$spapp = Import-SPAppPackage -Path .\spcdemoapp.app -Site http://server/sitecollection –Source ObjectModel

You can always add –confirm:$false to avoid getting prompted.

Now you have the AppPackage installed, you can deploy an instance of it to a subsite using Install-SPApp. You’ll need to provide a URL to the subsite using the –Web parameter and a reference to the imported app package. That’s why we saved the results of the last command into $spapp. Use the following command.

$instance = Install-SPApp -Web http://server/sitecollection/site -Identity $spapp

Like always with PowerShell, no news is good news. At this point, you should find the app installed on the Site Contents pages.

Here’s what it looks like it is running. This is mainly for reference when we start talking about updates.

To determine what apps are installed on a particular subsite use Get-SPAppInstance. This cmdlet can be executed three different ways. You need the id of the App Instance to update, export, or remove it. So often you combine it with a Where-Object command to get a reference to an app instance by name instead of by id.

$instance = Get-SPAppInstance -web http://server/sitecollection/site | Where-Object { $_.Title -eq "MyApp" }

Once you have a reference to the App Instance, removing the app from a subsite is easy with Uninstall-SPAppInstance.

Uninstall-SPAppInstance -Identity $instance

One nice feature of PowerShell is that you have the ability to export an installed app to a .app file using Export-SPAppPackage. It takes a parameter named -App. It expects the value from an instance called .App (so use Get-SPAppInstance as shown above). You also want to specify where to save the file using the –Path parameter.

Export-SPAppPackage –App $instance.App –Path .\ExportApp.app

When it comes to updating apps, that’s where things get a bit tricky. Here is what you need to do:

Get a reference to the existing installed instance using Get-SPAppInstance shown earlier
Import the new app package with Import-SPAppPackage
Use Update-SPAppInstance with a reference to the imported app package and the existing instance

Here are the commands

$instance = Get-SPAppInstance -web http://server/sitecollection/site | Where-Object { $_.Title -eq "MyApp" }

$spappv2 = Import-SPAppPackage -Path .\myapp.app -Site http://server/sitecollection/site -Source ObjectModel

Update-SPAppInstance – Identity $instance –App $spappv2

One thing you might have noticed by now is that there is no way to retrieve which app packages are installed nor is there any way to remove them using PowerShell. This is a bit different than the way we deal with solution packages. I suspect it cleans itself up, but I’m really not sure. I hope these PowerShell commands prove to be useful to you. Let me know if you run into any issues.

Creating SharePoint lists with Excel data using Access 2013

CoreyRoth — Thu, 28 Feb 2013 16:00:00 GMT

It’s not uncommon for users to want to move data from an Excel spreadsheet into a new SharePoint list. There have been various techniques to achieve this, but Access 2013 provides a way to this pretty easily. The process is pretty simple. We create a new Access 2013 database and import the Excel data. From there, we export it to SharePoint. Let’s look at the process. First, let’s take a look at my data in Excel.

To import it to SharePoint, start by creating a new blank Access 2013 database. The name doesn’t matter.

Now, we need to import the data from our Excel Spreadsheet. This is a multi-step wizard process but it isn’t too complicated. Go to the External Data tab and then click the Excel button under Import & Link.

On this step, browse to the path of your Excel file. I typically use the Import option, but you could use Append, or Link depending on your needs.

On the next step, you’ll be prompted for details about the data in your spreadsheet. You’ll get a preview of your data. It’s ideal if the first row of your spreadsheet has the column names.

On the next step, you can tweak the data types used in each column. This is important to ensure SharePoint sets the types for the columns appropriately. You’ll notice the format of your dates comes through weird but it will be ok in the end.

On this step, you can specify a primary key or create a new one. I’m not sure if SharePoint pays attention to this or not when the list is created.

Finally, you can confirm the name of the table you want to create.

At this point the data is now visible inside Access as you can see below. Now, we want to create the SharePoint list using this data. Under the Export section, click More and choose SharePoint List.

Now, a new wizard will guide you through importing the data in SharePoint. First, you will need to provide the URL to the site as well as the name of the list.

When it finishes, you’ll now see your data in SharePoint. You’ll notice it provides it to you in a grid view that you can immediately begin editing.

It seems to do a pretty good job of mapping to appropriate SharePoint column types as well. Take a look and note how it used types of Single line of text, Date and Time, Number, and Currency.

Keep in mind this is only an import process. The data is not synchronized. That means this will behave differently than taking an existing list and clicking the Export to Excel button. This seems like a pretty simply way to get data from Excel into SharePoint. I like it because it creates the list for you with little effort and it maps the data types for you. Do you find this useful? How do you import data from Excel?

Why I chose Surface RT over Surface Pro

CoreyRoth — Thu, 14 Feb 2013 21:09:00 GMT

I take my Surface RT everywhere and I do mean everywhere. Whether it is lunch, the bar, the airplane, user group presentation, a client demo, if I am out and about, chances are I have my Surface RT with me. In the past month or so (long before the Surface Pro) came out, I noticed this trend of people asking me if that was a Surface Pro. After I sighed, I would reply “No, it’s not and nor do I want one.” The technology just isn’t there yet for us to not have to make a trade-off right now. Today’s post is to explain why I chose what I did.

If you look at the Help Me Choose page, most of my reasons are clear. Let’s break it down.

ARM Processors

While uneducated reviewers out there are complaining about the Surface RT running on an ARM processor, I am praising it. When I first heard that Windows was going to support ARM, I knew the significance. This is what gives you a tablet device with no fan speed or heat concerns. It also gives you ridiculously long battery life and connected standby. I’ve used a Samsung Series 7 slate and it was heavy and sometimes loud. I saw the issue back then and I knew this was the answer. I’m a big fan of ARM.

Battery Life

Seriously, the battery life on Surface RT is amazing. They quote 8 hours, but I have used it all day at client meetings exclusively and then used it a couple of hours later at the bar and still had 20% left. I am seriously impressed. The Surface Pro unfortunately has significantly less battery life with reports between 3.5 and 5 hours. This may be fine if you plan on using it as a laptop and you’re keeping it plugged in but I like the fact that I never have to worry about power on my Surface RT. I charge it every other day typically and that is fine.

Connected Standby

This is the feature that makes your Windows RT device notify you of mail and other notifications when the device is “sleeping”. That means I hear every mail that comes in and I get that Skype call (usually) just like an iPad does. Surface Pro cannot do this because it goes into a true sleep just like your laptop does.

Instant Resume

Who has three seconds to wait for their device to come on every time they hit the button on top of it? You do, if you bought Surface Pro. I can turn the screen of my Surface RT on and off rapidly.

Apps

I am amazed at how many reviewers, said “ZOMG, the Surface RT can’t run Photoshop!”. Really? You’re dismissing the device because of this? How many times have you ran Photoshop on your iPad? And why would you run that on a tablet anyways? I get it. The Windows Store is still growing, but you can rest assure it will catch up to Apple and it’s five thousand fart apps. The install base of Windows PCs, Tablets, and other devices is just to huge to ignore.

When I think of this, I refer back to my post, "There’s an app for that, but does there need to be?” No, there is not a Facebook app for Windows 8, but do I need one? The reason they created one for mobile devices originally was the because the browser sucked. Well, I don’t need one because I have a fully functional web browser on the device (you can debate whether you like it or not :) ). When you use your laptop, do you wish there was a Facebook app there? No, of course not.

For you power users out there, you can actually run some of your favorite desktop apps over remote desktop. I don’t mean inside a full screen window session. I mean with Remote Apps which puts applications running on a remote server running seamlessly on your desktop. In fact, right now I am typing this entire post using Windows Live Writer running off of a Windows Azure VM on my Surface RT. Take a look at the screenshot below and notice how there isn’t any visible RDP window or anything like that.

So yes, that’s Visual Studio and Windows Live Writer running on my Surface RT desktop over RDP. It works quite well (assuming you have an Internet connection). Special thanks to @chakkaradeep for pointing out the post on this.

I even have a RemoteApp set up for Outlook. Yes, I agree the included Mail app is a bit painful. Really, my main complaint about it is that it’s slow and unresponsive. I’m hoping that will get better in the future. However, you have to understand why that app exists. It all comes back to Connected Standby. Outlook doesn’t support it, so they built this app that does. Sure, it could support it one of these days I am guessing, but it’s all a matter of priorities. Outlook definitely isn’t touch friendly.

Cost

The Surface RT is already a significant investment at it’s price point. With better hardware comes more cost of course. In reality, it’s not much more than any previous slate devices based on an i5 processor. You just have to decide what’s in your price range.

What about Surface Pro’s better hardware?

Like anything there is a trade-off. Yes, the higher resolution display and pen would be nice, but I could do without for now. Admittedly, I haven’t seen that display in person yet. I think the feature gap between the two devices will get closer as time goes on.

Can Surface RT replace your laptop?

Sometimes! When I am traveling, it’s often all I bring with me. If I have a SharePoint demo, I try to use SharePoint Online or I will remote into my laptop or another server so it gets the job done. I don’t write a ton of code any more so it’s ok that I don’t have Visual Studio running locally. With RemoteApps though, you can see that you can work around it. Take a look at this photo that I took before traveling a few weeks ago.

There you will see my Surface RT connected to a glowing USB hub (SharePoint branded) with a keyboard, mouse, and headset. It’s also attached to a second monitor driving it at full resolution as a second screen. Here I have a remote desktop connected to my laptop. I’m getting actual work done. Let’s see your iPad do that.

Can Surface RT replace your iPad?

At the risk of enraging the wrath of Apple fanbois, I’ll give you my opinion. If you want to get real work done, absolutely. If you want it to control your Sonos system or Directv receiver, not likely. For work though, there really is no comparison. Think back in the past to a meeting you have gone to right after someone you know first got their iPad. They are over there diligently trying to use the iPad in some useful way at work. Then, you see that person a few weeks later at another meeting and one of two things has happened. Either a) they didn’t bring the iPad or b) you peak on their screen and they are on Facebook or are playing Angry Birds. iPads are pretty decent for consumer home use, but for most people they aren’t going to help you get your job done.

Let’s face it Apple hasn’t done much since Steve Jobs died. I am hearing even the most die hard fans question their direction and capability to innovate. Simply making things thinner and lighter isn’t good enough for people. I think the Surface RT is superior to other devices in many ways. Does it have it’s issues? Sure, but this is Microsoft’s market to capture. Unfortunately, the marketing Microsoft is doing is just not effective so people just don’t know about what these devices do. When the word gets out, maybe we’ll see something.

What do you all think? Am I completely off base here? Does the RT meet your needs? Did you hold out for the Pro or did you go with something else? Leave your feedback.

Maybe I should have been a gadget reviewer for a living. If anyone wants to send me hardware for me to write my opinion about, I’ll take it. :)

Slides from my Publishing SharePoint Apps talk from Austin SharePoint Users Group

CoreyRoth — Thu, 14 Feb 2013 19:32:39 GMT

I had a great time last night at the Austin SharePoint Users Group (@AustinSPUG). We had a great turnout and we had a good discussion of what the publication process looks like with SharePoint 2013 Apps in the Office Store. Austin has a very friendly group of people. Never had I had so many people come up and thank me afterwards for speaking. Now, it makes me look forward to speaking at SharePoint Saturday Austin on 3/2. As promised, my slides are attached and are available on SlideShare.

Publishing SharePoint 2013 Apps to the Office Store

Speaking in Austin

CoreyRoth — Tue, 12 Feb 2013 17:35:07 GMT

The great thing about living in Texas is that there is three SharePoint users groups less than three hours away from me. I’m excited to have the opportunity to be speaking in Austin twice in the next couple weeks. The first talk is tomorrow night (2/13 at 6:00 pm) at the Austin SharePoint Users Group (@AustinSPUG) where I’ll be speaking about my experience publishing SharePoint 2013 Apps to the Office Store. It’s at the Microsoft office in Austin.

Then, I’ll be making a return trip on 3/2 for SharePoint Saturday Austin (@SPSATX) at the Etter-Harbin Alumni Center (Map). There, I’ll be talking about new development features in Visual Studio 2012. This talk will cover features that developers can take advantage of for both SharePoint 2010 and SharePoint 2013. I’m looking forward to seeing everyone. See you there!

How to: Perform a SharePoint 2013 site collection upgrade with PowerShell

CoreyRoth — Mon, 04 Feb 2013 23:11:30 GMT

At SPC12, I gave a talk about PowerShell in SharePoint 2013. In that talk I upgraded a SharePoint 2010 site collection to SharePoint 2013. I wanted to follow-up with a blog post showing the steps involved. To begin the process, I have restored a copy of my content database from my SharePoint 2010 environment on the SQL Server for my SharePoint 2013 environment. The first thing we need to do is mount the content database with Mount-SPContentDatabase. In SharePoint 2010, this process would actually update the database and perform the upgrade. Now, it actually just attaches the database but leaves the site running in SharePoint 2010 mode. Effectively you are running a full copy of SharePoint 2010 inside SharePoint 2013. You can do this and upgrade each site collection one at a time to make the transition process a bit easier.

Typically, when you are doing this, you’ll execute Test-SPContentDatabase first and resolve any reported issues. Just like in SharePoint 2010, you need to install all of your customizations via solution package prior to mounting. Test-SPContentDatabase can help you find some of these customizations if they are missing. For simplicity, I am going to leave that out of my example today. Mount-SPContentDatabase typically takes two parameters: the name of the database and the URL of the Web Application to bind it to. Here is what the command looks like.

Mount-SPContentDatabase –Name DatabaseName –WebApplication http://server

When it runs, you’ll see a progress indicator.

When it finishes, you’ll likely have errors. You can track them down and re-mount. More than likely you’ll always have some kind of error regardless of how hard you try.

Now you can go to the site in your web browser. You’ll see your existing site running in SharePoint 2010 mode along with a banner prompting to start the site collection upgrade process.

You can start the upgrade process right there in the browser, but we want to use PowerShell. We can see the upgrade status of our site collections using Get-SPSite. This cmdlet has been updated to show you the current version (ComaptibilityLevel) of the site collection. A value of 14 represents SharePoint 2010 while a value of 15 represents SharePoint 2013.

Get-SPSite

To upgrade a site collection, test it out first using Test-SPSite. Like Test-SPContentDatabase, this command can help you identify any particular issues. In my case, I am going to upgrade my root site collection.

Test-SPSite http://server/sitecollection

SharePoint 2013 has a new concept for the upgrade evaluation site collection. Effectively this process schedules a job to copy your site collection, upgrade it, and then optionally notify you (if you add the –email parameter). You don’t have to use this, but it’s a good way to test things out if you have a tricky site with a lot of customizations.

Request-SPUpgradeEvaluationSite http://server/sitecollection

Executing the command simply returns you to a command prompt. Later a job will fire off and create the upgrade evaluation site collection. This appears to be controlled by the Create Upgrade Evaluation Site Collections job. It only executes once a day so if you want to get your upgrade evaluation site faster, you can go manually run it. After it completes, you can visit your site by appending –eval to your site collection name (i.e.: http://server/sitecollection-eval). When you visit the site you’ll notice the warning bar at the top telling users that this is only temporary. After 30 days or so the site will get deleted automatically.

As you see I have an error in a web part that I need to correct. This is why upgrade site collections can be useful in finding issues before cutting over.

Let’s upgrade out site collection directly now. I only received warnings from Test-SPSite so I am going to proceed with the upgrade and assume everything is going to work fine. :) We use Upgrade-SPSite to make this happen. Pass the URL to the site collection and be sure and include –VersionUpgrade. It won’t upgrade to the new version if you leave off that parameter.

Upgrade-SPSite http://server/sitecollection –VersionUpgrade

Depending on the size of your site collection, it may take some time. When it finishes, you’ll see something similar to the screen below.

Now, we can visit our upgraded site in the browser.

Site Collections Upgrades are a powerful new feature in SharePoint 2013 which I believe will really make the process smoother. Keep in mind, you can also use the new Copy-SPSite cmdlet to make a copy of your site collection and perform some tests there.

User Group DOs and DON’Ts

CoreyRoth — Fri, 25 Jan 2013 16:00:00 GMT

As someone who has been a member, presenter, officer and board member of various user groups, I've come up with some observations on what makes a great user group. I would never call myself an expert on the subject (I reserve that for @Victor_Chat), but I think this is some good advice.

DO encourage and participate in a SharePint

Yes, I'm actually listing this first. More of the connections and relationships happen here than when mingling before the group. Attendees get the opportunity to let loose and it's a great way to get to know people. If you have questions, this is where you get them answered. The Houston SharePoint Users Group (HSPUG) does this right. It's not uncommon to see 40+ people at one of our SharePints. We actually have sponsors for it. :)

DO delegate

Some of the smaller groups tend to have one or two people that do everything. Ask for help and you will likely get it. There are usually people willing to help out. People can help with everything from signing people in to ordering food. If you're a member and want to help out, don't be afraid to ask what you can do.

DO encourage new speakers

You don't need big name speakers to have a good user group. Encourage new speakers to present to the group. When I was at Tulsa, we encouraged new speakers at every session. It was usually pretty effective.

DO seek out officers from diverse backgrounds

It's great to have officers from different backgrounds. Employ a healthy mix of consultants and non-consultants. Do this even if the officers work for a competitor. It shows that you aren't trying to dominate the user group with your company.

DO encourage others to meet up outside of the user group

This is something Houston is playing around with. We live in a large city and are encouraging members to get together throughout the month at a local bar or restaurant. We're still judging the success on this as I think it's yet to establish it's rhythm yet.

DO post your topics early

This sounds easy in theory but now that I have been involved with a few groups, I know it's not. Ideally, you want to line up multiple speakers months in advance. It is great if you can have these posted to the web site, include them in your communications, and even announce the next topics during each meeting.

DO engage in social media

Some groups do this better than others. Although probably less than 10% of your user group is on twitter, it's still a good way to remind users about what is going on throughout the month.

DON'T be afraid to ask questions

As a member, don't be afraid to ask questions of the presenter, the officers, or other members. Chances are there are users there that face the same challenges as you.

DON'T use vendor spotlights in place of presentations

Although it's great to support your sponsors, your users are there to learn, not to be sold to. It's ok, to let a vendor spend two minutes before a presentation and say hey thanks for letting us sponsor. However, it should never be used as a replacement for finding a speaker. Your users don't like this and it will drive them away from the group. Most user groups allow the vendor to set up a table and buy beers afterwards. This is more effective for them than giving a full-blown sales presentation.

DON’T sell your member list

We have vendors asking for the contact info of our members all the time. The answer to that request always is unequivocally NO. It is absolutely unacceptable to sell your members out like that. They expect some you to have some degree of ethics and decorum and not to sell their information away. If you run an ISV, under no circumstances should you ever send out a marketing E-mail from your company using the user group’s E-mail list. I’ve seen this happen and it makes me sick.

DON'T use the user group to promote your business

I attended a user group once where the self-promotion was so bad it made me sick. The first words out of your mouth shouldn't be about your company. The best officers I have seen have never even mentioned where they work once in front of the group. Your members will only tolerate this for so long before they stop coming. I've seen this nearly destroy groups before. It's ok to talk about your company afterwards over a beer. However, it's unacceptable to spend 15 minutes before the meeting talking about your company. Plus, this severely cripples sponsorship opportunities. As someone promoting your own business, you would never allow a competitor to sponsor. Plus, your competitors aren’t going to want to sponsor a corrupt user group anyways. Just don’t do it.

I remember one time in Houston, where someone did a 10 minute case study on a solution they built. Some of the members felt it was a bit salesy and were about to run them out the door. In reality, I didn't think it was salesy at all. The presenters were developers not account managers. However, you always have to be careful when doing case studies because they can come off as a sales pitch if you’re not careful.

Make your sales the old-fashioned way by playing golf, buying beers, and going to expensive dinners.

I may have bragged a little bit about my user group, but hey, it’s pretty awesome. Seriously, if you’re ever in town the third Wednesday of the month, you should make a point to attend. :) Hopefully, you find some of this information helpful. What tips do you have for user groups? Leave a comment and let me know.

Workaround for freezes in Client Web Part Editor in Visual Studio 2012

CoreyRoth — Thu, 10 Jan 2013 15:55:36 GMT

If you have tried to do any work with SharePoint 2013 Client Web Parts with the Office Developer Tools Preview 2 in Visual Studio 2012, you know it’s an exercise in frustration. It literally locks up every three or four lines of code you try to type. When it does this, it will freeze for ten seconds or more. This occurs when you are editing the page associated with the web part. It’s a total productivity killer.

It finally bugged me enough that I started looking for a solution. I was pretty close to switching to notepad. Luckily, I found a quick work-around by launching a different text editor. To launch another editor, right click on your web part page in the Solution Explorer and choose Open With…

Choose Source Code (Text) Editor.

This editor is similar to the Web Form Editor but it won’t lock up. You will lose IntelliSense and AutoComplete. However, I’d gladly close my own div tag to not have the editor lock up every ten seconds. The HTML is still color coded at least, but the JavaScript is not. Your JavaScript should be in a separate file anyways though. :) If you have been experiencing this issue, I hope this helps.

How to: Sort search results by query string with the ResultScriptWebPart in SharePoint 2013

CoreyRoth — Wed, 09 Jan 2013 20:21:09 GMT

By now you may have noticed that Search has changed quite a bit in SharePoint 2013. The ResultScriptWebPart powers most of the magic behind the Search Center. It replaces the CoreResultsWebPart that we have been using since SharePoint 2007. I expected many things in it to operate the same, but this web part really has been rewritten from the ground up and that’s a good thing. One new feature (of many) it brings us is the ability to sort search results. You can specify a sort order in the query or by enabling it in the web part properties. This allows the user to pick from a list of properties. I’ll cover it in the future because it deserves a quick post. However, for you developers out there, I know that some of you will want to write some code that passes a sort order. This post explains how to do it.

Before we begin, you have to know what you can sort of. There are a lot of options out-of-the-box such as Author and Write (Modified Date) or you can use your own property. Whatever you choose, you need to check the managed properties page and make sure it has the Sortable option set to Yes - active. You do this from the Search Schema page on your site collection or Search Service Application.

Since SharePoint 2007, we have been able to pass a query using KQL using the “k” parameter to the results.aspx of your search center. We can still do this in SharePoint 2013. To add a sort order though, we do things a little differently. Using a new query string parameter called Default, we can pass in a number of properties including sort order. The format is quite a bit different though as it uses a JSON notation. To start, I am going to issue a query with out k parameter using this new JSON notation. Let’s do a search for our sales documents. To do this, I include my search center URL (/search/pages/results.aspx) and append #Default= to it followed by the JSON object with a name value pair {"k":"Sales"}. When I assemble to entire string, it looks something like this.

http://server/search/Pages/results.aspx#Default={"k":"Sales"}

Now we want to add sorting. To do that, we use the “o” parameter. It takes a collection of JSON objects. The parameter p represents the managed property to sort by and the value d is the sort direction specified as a 0 or 1. A value of 0 represents ascending and a value of 1 represents descending. For example to sort by modified date descending, we use the Write managed property. The string would look like this:

"o":[{"d":1,"p":"Write"}]

When we add it to our query string from above it looks like this.

http://server/search/Pages/results.aspx#Default={"k":"Sales","o":[{"d":1,"p":"Write"}]}

This shows us the newest documents. In SharePoint 2013, they moved the modified date to the InfoCard so you actually have to hover over a search result to see the date. To show the oldest documents, you would just specify d:'”0” instead.

As another example, we could also sort by Author.

http://server/search/Pages/results.aspx#Default={"k":"Sales","o":[{"d":0,"p":"Author"}]}

I’ve included a bigger screenshot where you can see the name of the first author in the list on the InfoCard.

We can also combine them to have multiple sort orders, but I have had mixed results with that so far. Here’s what the query string would an example look like though.

http://server/search/Pages/results.aspx#Default={"k":"Sales","o":[{"d":0,"p":"Write"},{"d":1,"p":"Author"}]}

I’m pretty excited about sorting functionality in the search center. Users have been wanting it for quite a long time and only a select few ever had it (those with FAST Search for SharePoint). If you are writing search solutions, be sure and check my post about sorting with the REST API. This technique works with both SharePoint 2013 on-premises as well as SharePoint Online Preview. All of the screenshots came from Office 365.

No metadata? No problem! Custom entity extraction in SharePoint 2013

CoreyRoth — Tue, 08 Jan 2013 16:00:00 GMT

Every organization wants better search results. However, few have actually spent the time to create file plans, content types, and managed properties to make it happen. SharePoint 2013 has a feature called entity extraction though that can actually infer values by comparing what it finds in the body of the document to a dictionary. This feature is Entity Extraction. If you are familiar with FAST Search for SharePoint or FAST ESP, you know that entity extraction is nothing new. What it does is gives you the power to infer the values of managed properties in search without having metadata in your site columns. FS4SP and SharePoint 2013 come with an extraction dictionaries for company names out-of-the-box. This means when it crawls it will search the contents of the body of your documents and if it recognizes any companies it knows, you can then search and refine on it. However, the true value comes when you create your own. SharePoint 2013 makes it really easy to create these custom dictionaries.

Let me give you a few more examples to help you really understand the significance. Most companies have a concept of a department or business unit. We can create a dictionary with all of the company’s departments such as Accounting, Human Resources, IT, Operations, etc. With entity extraction, if it finds a document and somewhere the text “Human Resources Organization Chart” is found, it then sets the value of the managed property to Human Resources. Now, when the user does an advanced search and says “show me all Human Resources documents”, that result comes back with more confidence. By using the extraction dictionary, we get better results that just using a regular keyword search. Now you may be wondering that’s nothing special, but we can also add other terms, for example, I could add “HR”, and “Benefits” to that dictionary as well and map them to the Human Resources department. Once I have a property defined like this, I can combine it with others as well. This will let us issue queries like “show me all documents from Human Resources with a document type of Policy”.

As another example, you could pre-load SharePoint with a dictionary of product names. For those of you in the energy industry, you could pre-populate it with a list of wells or names of leases. Are you starting to see the significance? In previous versions of SharePoint, we had to set site columns in our document libraries to capture these values either from the user or programmatically. Now with the right dictionary, we can assume the values with a reasonable degree of confidence.

Alright, enough explanation, let’s see this in action and hopefully it will make sense. MSDN has a great post on this but I found and error in it so that is why I am writing this post (plus I know you all like screenshots). For my example, I have a bunch of PowerPoint documents about SharePoint 2013 on my site. I’ve created a custom entity extraction dictionary that will help me refine these documents by feature in SharePoint (i.e.: Apps, Business Intelligence, Search, Social, etc).

Before you build your dictionary file though, you need to decide on what type of extraction to use. You can choose whether you want it to match a word or just part of it. You can also specify whether it needs to match exactly. The MSDN article summarizes this well, but here’s a quick recap of your choices.

Word Extraction – case-insentive, word has to match, limited to 5 dictionaries
Word Part Extraction – case-insensitive, only part of a word has to match, limited to 5 dictionaries
Word Exact Extraction – case-sensitive, word has to match, limited to 1 dictionary
Word Part Exact Extraction – case-sensitive, only part of a word has to match, limited to 1 dictionary

For today’s example, I am going to use Word Part Extraction as it gives you some of the most flexibility. You might want to use Word Exact Extraction for extracting IDs from a document. For example, you could use it to extract part numbers or invoice numbers. Those aren’t something you would typically want to refine on but you may want to query on them. FAST Search for SharePoint only provided case-sensitive extraction. This made the feature less useful as you had to accommodate all possible varieties of case combinations in your dictionary file.

To get started, we need to create a dictionary file. I started with notepad and I also edited with Excel some. The format is simple “Key,Display form”. The key is what the crawler matches in the body of the document and the Display form is what gets displayed in the refiner. Although the Display form is optional, you want to include it as it allows you to control the exact way the text looks in the refiner (including case sensitivity). Here’s the dictionary file I created.

Key,Display form
bcs,Business Connectivity Services
Business Connectivity Services,Business Connectivity Services
wcm,Web Content Management
Web Content Management,Web Content Management
bi,Business Intelligence
Business Intelligence,Business Intelligence
ecm,Electronic Content Management
Electronic Content Management,Electronic Content Management
Apps,Apps
Analytics,Analytics
Development,Development
Service Application,Service Application
Excel Services,Excel Services
Office Web Apps,Office Web Apps
owa,Office Web Apps
wac,Office Web Apps
PerformancePoint,Business Intelligence
Search,Search
Social,Social
My Sites,My Sites
Communities,Social
Visio Services,Visio Services
Workflow,Workflow

The next step is to use the PowerShell command, Import-SPEnterpriseSearchCustomExtractionDictionary. The documentation on this page is correct which is how I found the solution to my problem. The first step is to get a reference to the Search Service Application using Get-SPEnterpriseSearchServiceApplication. Then for our import command, we pass the service application, the Filename, and the DictionaryName. Here’s where the complexity comes in. The Filename requires a UNC path. That means something like \\servername\path\file.csv. It won’t take a relative path. The next tricky part is where I found an issue in the documentation. I wanted to use the Word Part extraction, it has the case of the word “WordPart” incorrect in the dictionary name. If you do specify the DictionaryName wrong, it will not work. Here are the list of valid values which correspond to the extraction types we talked about above.

Microsoft.UserDictionaries.EntityExtraction.Custom.Word.n [where n = 1,2,3,4 or 5]
Microsoft.UserDictionaries.EntityExtraction.Custom.ExactWord.1
Microsoft.UserDictionaries.EntityExtraction.Custom.WordPart.n [where n = 1,2,3,4 or 5]
Microsoft.UserDictionaries.EntityExtraction.Custom.ExactWordPart.1

For the non-exact entries, you need to specify a value at the end (1 – 5) which specifies which extraction dictionary it uses. In the case below, I did number 2 since I already messed up number 1 by specifying the dictionary name incorrectly. :)

$searchApp = Get-SPEnterpriseSearchServiceApplication

Import-SPEnterpriseSearchCustomExtractionDictionary –SearchApplication $searchApp –Filename \\server\c$\folder\WordPartExtraction.csv –DictionaryName Microsoft.UserDictionaries.EntityExtraction.Custom.WordPart.2

When you run the commands, it will look like this. I put the above in a script file for convenience.

The next part I believe is a little different than the way you did it with FAST Search for SharePoint. What you need to do is tell search which managed properties to perform entity extraction. Effectively, what we are doing here is telling search to look at the body of the document and see if anything in there matches items in the dictionary. To do this, go to your Search Service Application –> Search Schema and edit the property named body.

Scroll to the bottom and you will see the Custom entity extraction section. Now, we just need to check the box next to the dictionary we want to use. In my case, it is Word Part Extraction – Custom2. If you have multiple dictionaries you may select them here. Save the managed property after you make your selection.

After you save, you need to start a full crawl on your content source, typically Local SharePoint sites.

When this finishes, we can now begin to use our new extracted entities in our search center. The first thing we want to do is add this new extraction to the Refinement web part so that users can refine results by SharePoint feature. Go to your Search Center and issue a query that is going to get you some results that you know you can refine on. In my case, I typed the word SharePoint since I knew all of my documents were related to that. Once you get search results, edit the page. Then on the left side, edit the Refinement web part. Now, click the Choose Refiners button.

This page will list all managed properties marked for refinement. What’s really nice is that when you click on a managed property, it gives you a preview of the available refiners.

In the list of available refiners, I select WordPartCustomRefiner2. Below, you see a list of Sample values and the number of times it found a match. To configure the property, select it and click the Add button. I also added this new refiner up to the top since I want users to see it first.

Now, I gave it a Display name and you have the option to choose a different Display template as well as how it is sorted. You can actually customize how the refiner is rendered on the page with the display template too but that’s outside of the scope of today’s post. At the bottom of the page there is also a Preview button. Click on it and you will see what your search results look like before you even save the page.

If you’re happy with the way the refiners look, save the page, check it in, and publish it. Now issue a query. I am going to use the same one from before.

As you can see, we now see a list of the SharePoint features that we specified in our dictionary. Let’s try a few refiners. Let’s start by selecting Electronic Content Management. I do know that should it read Enterprise, but it was after midnight when I started working on this. :)

Notice, that in the results, that Word Document 3 comes back and you see “ECM” in it. That’s the only text in the document and it matched it to that feature since we defined it in the dictionary. Now let’s try Business Connectivity Services.

It returns several slide decks this time because it mentions it in the Intro deck, the BCS deck, UPS, etc. I’m not sue how Visio Services made a hit to it, but maybe there is something new I need to learn. :)

You can also select multiple refiners. In this case, I selected Apps and Web Content Management.

By now, I am hoping you are seeing the power of entity extraction. It gives you a new level of classification on documents and the users never had to tag anything manually at all.

You can issue queries with these dictionaries as well too. For example, if I want to search for anything tagged with Apps, I would issue the following query.

WordPartCustomRefiner2:"Apps"

I hope after reading this post, it has got you started thinking. Most organizations have next to no metadata on their documents. This isn’t a replacement for taking the time to classify your documents properly with site columns and content types. Inferring metadata will never be as good as the users taking the time to classify the documents themselves. However, it is a great stop-gap in dealing with all of that untagged content you have.

I think this is one of the most significant feature in SharePoint 2013 that most people will probably never use. :( Take the time to set up a few dictionaries and you are going to get immediate value out of search and your users are going to notice.

List of common SharePoint 2013 Result Source IDs

CoreyRoth — Fri, 04 Jan 2013 16:08:06 GMT

Although the new Result Source feature in SharePoint 2013 is really cool, writing queries against them is not. With scopes you could specify them by name (i.e.: All Sites or People). However with result sources, you must specify the id not the name. This cane make it tricky to develop custom coded solutions. Luckily, it turns out that the IDs of the built-in result sources are all the same (at least they appear to be) with the exception of the Conversations result source. In comparing an on-premises installation of SharePoint 2013 with a SharePoint Online Preview tenant, here is the list I came up with. Hopefully, it will save you some time when you need to write a query.

Result Source	ID
Documents	e7ec8cee-ded8-43c9-beb5-436b54b31e84
Items matching a content type	5dc9f503-801e-4ced-8a2c-5d1237132419
Items matching a tag	e1327b9c-2b8c-4b23-99c9-3730cb29c3f7
Items related to current user	48fec42e-4a92-48ce-8363-c2703a40e67d
Items with same keyword as this item	5c069288-1d17-454a-8ac6-9c642a065f48
Local People Results	b09a7990-05ea-4af9-81ef-edfab16c4e31
Local Reports And Data Results	203fba36-2763-4060-9931-911ac8c0583b
Local SharePoint Results	8413cd39-2156-4e00-b54d-11efd9abdb89
Local Video Results	78b793ce-7956-4669-aa3b-451fc5defebf
Pages	5e34578e-4d08-4edc-8bf3-002acf3cdbcc
Pictures	38403c8c-3975-41a8-826e-717f2d41568a
Popular	97c71db1-58ce-4891-8b64-585bc2326c12
Recently changed items	ba63bbae-fa9c-42c0-b027-9a878f16557c
Recommended Items	ec675252-14fa-4fbe-84dd-8d098ed74181
Wiki	9479bf85-e257-4318-b5a8-81a180f5faa1

Of course this doesn’t help you much for your own custom result sources, but at least you should be able to work with this list for anything built-in. This is especially useful if you want to write queries to do people search or get popular items.

How to: Pass parameters to a Client Web Part

CoreyRoth — Fri, 04 Jan 2013 16:00:00 GMT

This is one of those posts that I have promised to write but I totally forgot about. What I want to talk about today is passing parameters to SharePoint 2013 Client Web Parts. These parameters are equivalent to the properties on traditional web parts. The process is relatively straight forward, but I thought I would share some of my experiences with it. This article on MSDN will get you started, but I do things a bit differently.

Unfortunately, the updates to the tools with Preview 2 don’t add anything to make this process easier. There are three steps to adding a property to a client web part.

In elements.xml, add a property element which contains the description, type, default value, and other information.
In elements.xml, edit the query string of the src attribute of the Content element to pass the parameter to the client web part page.
Write JavaScript code to receive the value of the parameter.

When it comes to Client Web Part parameters, there are four types:

string
boolean
int
enum

You will use the above values in the Type attribute of the property you add. It must match exactly. Let’s take a look at the Property element and see what the values do. In this case, we’ll add a string property. In Preview 1, the elements.xml file used to include a commented example, but now that’s gone. Here’s an example.

<Property Name="MyString" Type="string" WebBrowsable="true" WebDisplayName="Ny String" WebDescription="Text description of my string" WebCategory="Configuration" DefaultValue="Default My String" RequiresDesignerPermission="true" />

Aside from the type, the properties that you will probably care about are the following:

Name – name of the parameter you will query by JavaScript
Type – data type
WebDisplayName – name of the parameter displayed to the user in the web part properties
WebDescription – description of the parameter displayed to the user
WebCategory – group name in the web part properties
DefaultValue – the default value if the user does not change it

The Property element looks similar for both boolean and int types as well. However, if you specify enum, the user will see a dropdown list of values. It will contain an EnumItems child element which looks like this.

<Property Name="MyEnum" Type="enum" RequiresDesignerPermission="true" DefaultValue="1" WebCategory="Configuration" WebDisplayName="Enum property">
  <EnumItems>
    <EnumItem WebDisplayName="Choice 1" Value="1"/>
    <EnumItem WebDisplayName="Choice 2" Value="2"/>
    <EnumItem WebDisplayName="Choice 3" Value="3"/>
  </EnumItems>
</Property>

Once you finished defining your properties, you need to add them to the query string. Effectively, SharePoint passes the values the user specifies by query string to the client web part page. Each parameter comes in two pieces: the value your JavaScript will query and the the name from each Property element. Each parameter looks something like this.

Parameter1=_Parameter1_

The value of the parameter is always enclosed in underscores (_). For the two parameters we added above, here is what our src attribute will look like. I’m using the same app part I created for the Preview 2 blog post.

<Content Type="html" Src="~appWebUrl/Pages/ClientWebPart1.aspx?MyString=_MyString_&amp;MyEnum=_MyEnum_&amp;{StandardTokens}" />

You’ll also notice that I have included {StandardTokens}, this tells SharePoint to provide common useful values such as the URL to the Host Web (SPHostUrl).

Now, we need to add JavaScript to the client web part itself to read the value and do something with it. I use a helper method to help get query string values. I’m pretty sure I got this method from one of the early SharePoint app examples but I’m not sure entirely.

function getQueryStringParameter(urlParameterKey) {
    var params = document.URL.split('?')[1].split('&');
    var strParams = '';
    for (var i = 0; i < params.length; i = i + 1) {
        var singleParam = params[i].split('=');
        if (singleParam[0] == urlParameterKey)
            return decodeURIComponent(singleParam[1]);
    }
}

Using this method, we just request a value for the name of our parameters. In my example below I simple assign the value to a div.

$("#myString").text(getQueryStringParameter("MyString"));
$("#myEnum").text(getQueryStringParameter("MyEnum"));

Now, when we add the App Part to the host web, we can configure it. In the case I gave, you can find the values in the Configuration header.

The values I selected can then be seen in the web part on the page.

When you’re ready to add properties to your client web parts, I hope this post helps. It’s not too complicated but it is a bit tedious. Give it a try and see how it works for you.