XDocument Geo = default(XDocument);

    internal const string Unknown = "unknown";

    protected override void FillResolve(Uri context, string[] entityTypes,

      string resolveInput, List<PickerEntity> resolved)

    {

      // proceed only if looking for correct entity type

      if (!entityTypes.Contains(SPClaimEntityTypes.FormsRole))

        return;

      // Search all possible Claims values for a match or partial match with the

      // input parameter string resolveInput. For each match/partial match found,

      // add an entry to the parameter List<PickerEntity> resolved.

      // The Claims Picker will detect whether any of the List<PickerEntity>

      // entries are exact matches, and indicate a match (resolution) by underlining

      // the string and adding a trailing semi-colon. For non-matches, a squiggly

      // underline is created, and a tooltip alerts the user to partial matches.

      string inputText = resolveInput.ToLower();

      string groupName = default(string);

      EnsureGeoData();  // This loads the geographic data XML file into the XDocument "Geo"

      string c = Unknown;

      string r = Unknown;

      string p = Unknown;

      foreach (var country in Geo.Descendants("Country"))

      {

        try { c = country.Attribute("name").Value; }

        catch { }

        if (c != Unknown && c.ToLower().Contains(inputText))

        {

          groupName = GetHierarchyNodeNameForNodeID(CountryClaimType);

          PickerEntity pickerEntity = CreatePickerEntity(

            CountryClaimType, c,

            CountryClaimValueType, groupName);

          resolved.Add(pickerEntity);

        }

        // regions

        foreach (var region in country.Descendants("Region"))

        {

        // remaining code omitted for brevity . . .

    }

This searches the GeoRegion Claims datasource, (an XML file), for all possible matches to the text the user typed into the Users/Groups textbox. All matches (whether exact or partial), are added as PickerEntities to the parameter List<PickerEntity> resolved. The Claims Picker will determine whether any are exact matches.

This image shows the squiggly underlining indicating a non-match.

When the user clicks on the squiggly-underlined text, a tooltip shows the partial matches returned by the Claims Provider:

The helper methods GetHierarchyNodeNameForNodeID and CreatePickerEntity need some explanation. They will be discussed after looking at the second overload of method FillResolve.

The second overload differs in that it is called by SharePoint implicitly, after a successful search on the Claims Picker search page, before it returns to the Claims Picker control. This is simpler, since the Claim value is already known, and just needs to be reported as a PickerEntity. That code would look something like this:

    protected override void FillResolve(Uri context,

      string[] entityTypes, SPClaim resolveInput,

      List<PickerEntity> resolved)

    {

      // proceed only if looking for correct entity type

      if (!entityTypes.Contains(SPClaimEntityTypes.FormsRole))

        return;

      string groupName = GetHierarchyNodeNameForNodeID(resolveInput.ClaimType);

      PickerEntity pickerEntity =

        CreatePickerEntity(resolveInput.ClaimType,

        resolveInput.Value, resolveInput.ValueType, groupName);

      resolved.Add(pickerEntity);

    }

Here it is in action. In this image, a search for "vir" returned two partial matches, West Virginia and Virginia:

If the user selects one of these, and clicks the Add button, the second FillResolve method overload fires (the one with SPClaim as the third parameter). Subsequently clicking the OK button will close this dialog and return to the Claims Picker control.

Claim Types are HierarchyNodeIds

Key to understanding this hierarchy implementation is the use of Claim Types as node IDs, and that left pane (UI) tree node labels and right pane search result (UI) group labels are the same. Claim Types have been constructed to be self-describing.

In both methods FillHierarchy and FillSearch, a parameter of type SPProviderHierarchyTree is passed in. This represents the tree visible in the left pane of Select People and Groups -- Webpage Dialog. Each node of the tree is internally labeled with an ID (hierarchyNodeID), and that ID is the Claim Type. Tree nodes are type SPProviderHierarchyNode; the constructor looks like this:

     New SPProviderHierarchyNode(string providerName, string nodeName, string hierarchyNodeID, bool isLeaf);

The second parameter, nodeName, is what appears as the UI node label in the left pane of the Webpage Dialog, while hierarchyNodeID is the internal label. When search results appear in the right pane, nodeName will become the group name. Let's see it.

Search results for USA regions where the region name contains "th":

The USA node above is a USA region Claim Type. Any Claim Values found by the search are stored inside the USA region node, in property EntityData.

A couple of base class methods should be used when creating SPClaims or PickerEntities; not using them can lead to errors. (See Tips and Known Issues - http://msdn.microsoft.com/en-us/library/ff625762.aspx - for more information.) Here's an example of creating PickerEntities and Claims using base class methods CreatePickerEntity and CreateClaim:

    private PickerEntity CreatePickerEntity(string claimType,

      string claimValue, string claimValueType, string groupName)

    {

      PickerEntity entity = base.CreatePickerEntity();

      entity.Claim = CreateClaim(claimType, claimValue,

        claimValueType);

      entity.EntityType = SPClaimEntityTypes.FormsRole;

      entity.EntityGroupName = groupName;

      entity.DisplayText = claimValue;

      entity.Description = groupName + ": " + claimValue;

      entity.IsResolved = true;

      return entity;

    }

Helper method GetHierarchyNodeNameForNodeId method just decodes the Claim Type passed to it, and returns the embedded value closest to the leaf level:

    private string GetHierarchyNodeNameForNodeID(

        string hierarchyNodeId)

    {

      if (string.Equals(hierarchyNodeId,

          CountryClaimType,

          StringComparison.OrdinalIgnoreCase))

      { return "Country"; }

      Hashtable claimBits = DecodeClaimType(hierarchyNodeId);

      if (Unknown != (string)claimBits["Region"])

        return (string)claimBits["Region"];

      else

        return (string)claimBits["Country"];

    }

Example: For Claim Type "http://sharepointdevelopers.net/2011/02/claims/Country#Canada/Region", GetHierarchyNodeNameForNodeId would return Node Name "Canada".

FillHierarchy and FillSearch

These two methods interact with each other, and so are discussed together. Method FillHierarchy alters the left pane of the search page, and sets it up to filter the search. It is called when the user clicks on a hierarchical level, and adds the next child level nodes. For example, clicking the Country node adds all its possible child nodes:

Clicking the USA node adds all its possible child nodes:

If the user clicks a node, thus selecting it, and then searches, any search will be scoped to just the level that node represents like this:

The code would look something like this:

    protected override void FillHierarchy(Uri context,

      string[] entityTypes, string hierarchyNodeID,

      int numberOfLevels, SPProviderHierarchyTree hierarchy)

    {

      // proceed only if looking for correct entity type

      if (!entityTypes.Contains(SPClaimEntityTypes.FormsRole))

        return;

      EnsureGeoData();

      // A null id indicates the root of the tree

      // Add hierarchy root node

      if (null == hierarchyNodeID)

      {

        hierarchy.AddChild(

          CreateHierarchyNodeForNodeID(CountryClaimType,

          false));

      }

      // Add Region nodes (scopes search to region)

      if (IsACountryClaimType(hierarchyNodeID))

      {

        foreach (var country in Geo.Descendants("Country"))

        {

          string c = Unknown;

          try { c = country.Attribute("name").Value; }

          catch { }

          if (c != Unknown)

          {

            string claimType = GetRegionClaimType(c);

            hierarchy.AddChild(

              CreateHierarchyNodeForNodeID(claimType, false));

          }

        }

      }

      // Add Province nodes (scopes search to province)

      if (IsARegionClaimType(hierarchyNodeID))

      {

        Hashtable claimBits = DecodeClaimType(hierarchyNodeID);

        string c = (string)claimBits["Country"];

        try

        {

          var regions = Geo.Descendants("Country")

            .Where(country =>

              country.Attribute("name").Value == c)

            .FirstOrDefault().Descendants("Region");

          foreach (var region in regions)

          {

            string r = region.Attribute("name").Value;

            string claimType = GetProvinceClaimType(c, r);

            hierarchy.AddChild(CreateHierarchyNodeForNodeID(

              claimType, true));

          }

        }

        catch { }

      }

    }

    // Helper method

    private SPProviderHierarchyNode

      CreateHierarchyNodeForNodeID(string hierarchyNodeID,

      bool isLeaf)

    {

      return new SPProviderHierarchyNode(this.Name,

      GetHierarchyNodeNameForNodeID(hierarchyNodeID),

      hierarchyNodeID, true);

    }

The FillHierarchy code decodes the Claim Type passed in as parameter hierarchyNodeID, and figures out what part of the hierarchy was clicked. Using the decoded Claim Type, it looks up the same node in the GeoRegion datasource, finds the child nodes there, then uses those to create new SPProviderHierarchyNode nodes, and adds them to parameter SPProviderHierarchyTree hierarchy, which is the node the user clicked.

What is the business user searching for? Claims values. Here's a possible implementation of FillSearch:

    protected override void FillSearch(Uri context,

      string[] entityTypes, string searchPattern,

      string hierarchyNodeID, int maxCount,

      SPProviderHierarchyTree searchTree)

    {

      // Look for a match on searchPattern text

      // Find/create appropriate child node(s) in searchTree

      // When a searchPattern matches, create a PickerEntity,

      // add it to the appropriate node.

      // hierarchyNodeID will identify the scope to be searched

      // A null hierarchyNodeID indicates no node was

      // selected, an empty one indicates the Provider node,

      // the rest will have a Claim Type

      string searchText = searchPattern.ToLower();

      PickerEntity pickerEntity = default(PickerEntity);

      string groupName = default(string);

      SPProviderHierarchyNode node = default(SPProviderHierarchyNode);

      EnsureGeoData();

      SearchScope scope = SearchScope.All;

      if (IsACountryClaimType(hierarchyNodeID))

      { scope = SearchScope.Country; }

      else if (IsARegionClaimType(hierarchyNodeID))

      { scope = SearchScope.Region; }

      else if (IsAProvinceClaimType(hierarchyNodeID))

      { scope = SearchScope.Province; }

      // search all

      var found = Geo.Descendants()

              .Where(d => d.HasAttributes &&

                d.Attribute("name").Value.ToLower().Contains(searchText));

      string cType = default(string);

      foreach (var geoRegion in found)

      {

        var parents = geoRegion.Ancestors().Where(a => a.HasAttributes);

        switch (parents.Count())

        {

          case 0: // country

            if (!

                (scope == SearchScope.All ||

                 scope == SearchScope.Country))

            { continue; }

            groupName = GetHierarchyNodeNameForNodeID(CountryClaimType);

            pickerEntity = CreatePickerEntity(CountryClaimType, geoRegion.Attribute("name").Value,

              CountryClaimValueType, groupName);

            node = GetNodeForClaimType(searchTree, CountryClaimType, false);

            node.AddEntity(pickerEntity);

            break;

          case 1: // region

            if (!

              (scope == SearchScope.Region ||

              scope == SearchScope.All))

              continue;

            cType = GetRegionClaimType(parents.First().Attribute("name").Value);

            if (scope == SearchScope.Region && cType != hierarchyNodeID)

              continue;

            groupName = GetHierarchyNodeNameForNodeID(cType);

            pickerEntity = CreatePickerEntity(cType, geoRegion.Attribute("name").Value,

              RegionClaimValueType, groupName);

            node = GetNodeForClaimType(searchTree, cType, false);

            node.AddEntity(pickerEntity);

            break;

          case 2: // province

            if (!

              (scope == SearchScope.Province ||

              scope == SearchScope.All))

              continue;

            cType = GetProvinceClaimType(

             parents.ElementAt(1).Attribute("name").Value,

             parents.ElementAt(0).Attribute("name").Value);

            groupName = GetHierarchyNodeNameForNodeID(cType);

            if (scope == SearchScope.Province && cType != hierarchyNodeID)

              continue;

            pickerEntity = CreatePickerEntity(cType, geoRegion.Attribute("name").Value,

              ProvinceClaimValueType, groupName);

            node = GetNodeForClaimType(searchTree, cType, true);

            node.AddEntity(pickerEntity);

            break;

        }

      }

    }

    // Helper method

    private SPProviderHierarchyNode GetNodeForClaimType(

      SPProviderHierarchyTree searchTree, string claimType,

      bool isLeaf)

    {

      SPProviderHierarchyNode node = default(SPProviderHierarchyNode);

      if (searchTree.HasChild(claimType))

      {

        node = searchTree.GetChild(claimType);

      }

      else

      {

        node = CreateHierarchyNodeForNodeID(claimType, isLeaf);

        searchTree.AddChild(node);

      }

      return node;

    }

The search attempts to match the text the user typed into the Find textbox with all values from the GeoRegion datasource. For all matches/partial matches, the code figures out the level of the hierarchy for that match by finding the equivalent node in the GeoRegion datasource, then checking on the XML ancestors of that node. It constructs a Claim Type from those ancestors. Then it checks whether the current search scope (the hierarchyNodeID/ClaimType from the node that the user clicked) agrees with the constructed Claim Type. If so, the value is within the search scope, and it is just a matter of creating a PickerEntity and adding it to the correct node of the search tree. If the search tree node does not already exist, then it is created by helper method GetNodeForClaimType.

Note that in this implementation, the search results use a flat hierarchy in the left pane, in order to make the UI more intuitive.

Here's why. For search results, each node in the search tree control shows the total number of results for everything below and including that node, and the number shown can be a little confusing if the hierarchy tree is created. For example, searching for "a", and building the left pane hierarchy would look like this:

Hmmm - there are not 55 countries! There are a total of 55 results representing states, regions, and countries in the Country node and all the child nodes under it.

If the search builds a flat hierarchy, the visual display seems more natural, as seen in this screenshot, where there are 2 results for Country, 4 regions in the USA, 8 states in the USA-North region, using the same search for "a":

Note that after searching, clicking any node in the left pane will refresh the right pane with just the results for that node's scope - and this happens client-side.

Authorization

Authorization using the returned Claim Value works the same way as for Domain Groups or FBA Roles- pick a geographic region in the Claims Picker, and assign it to a SharePoint Group, or assign it permissions directly. It shows up like this on the Permissions page:

SharePoint treats Claims as if they were Domain Groups, hence the Type in the image above. In the screenshot, all users with a Claim Value of USA-South are authorized at the Design permission level. Since each user has three geographic region claims, this can become a broader scope (Country), or finer (Province). And, best of all, no need for an administrator to manually manage a multitude of SharePoint groups. When the user's data is updated in Active Directory (or wherever the location data lives), then the custom Claims Provider will automatically create new Claims at login time that match the new user data. That's a win-win!