I've moved my blog to!. Please update your links. This blog is no longer in use--you can find all posts and comments at my new blog; I will no longer be posting to this site and comments have been disabled.

Saturday, August 9, 2008

Displaying Audience Rules via STSADM

Okay, so you've created your audience and used my gl-addaudiencerule command to add some complex rules to the audience.  Three months later you've forgotten what those rules are and need to see them again - unfortunately you can't do that via the browser, so what do you do?  Simple, you run gl-enumaudiencerules, another command I've created to help manage audiences via STSADM.

This command is really simple so I'll be brief - I simply loop through all the rules associated with an audience and display back an XML structure representing those rules.  The nice thing about this is that you can use it to help build your rules to assign using the gl-addaudiencerule command - you'd create all the rules you need via the browser, with no groupings, and then use this command to get the XML and then simply add your grouping elements into the XML - this way you're sure the field names are correct.

Here's a snippet of the code:

   2: /// <summary>
   3: /// Returns an XML structure containing all the rules associated with the audience.
   4: /// </summary>
   5: /// <param name="sspName">Name of the SSP.</param>
   6: /// <param name="audienceName">Name of the audience.</param>
   7: /// <param name="includeAllAttributes">if set to <c>true</c> [include all attributes].</param>
   8: /// <returns></returns>
   9: private string EnumRules(string sspName, string audienceName, bool includeAllAttributes)
  10: {
  11:     ServerContext context;
  12:     if (string.IsNullOrEmpty(sspName))
  13:         context = ServerContext.Default;
  14:     else
  15:         context = ServerContext.GetContext(sspName);
  17:     AudienceManager manager = new AudienceManager(context);
  19:     if (!manager.Audiences.AudienceExist(audienceName))
  20:     {
  21:         throw new SPException("Audience name does not exist");
  22:     }
  24:     Audience audience = manager.Audiences[audienceName];
  26:     ArrayList audienceRules = audience.AudienceRules;
  28:     if (audienceRules == null || audienceRules.Count == 0)
  29:         return "The audience contains no rules.";
  31:     string rulesXml = "<rules>\r\n";
  32:     foreach (AudienceRuleComponent rule in audienceRules)
  33:     {
  34:         if (includeAllAttributes)
  35:         {
  36:             rulesXml += string.Format("\t<rule field=\"{1}\" op=\"{0}\" value=\"{2}\" />\r\n", rule.Operator, rule.LeftContent, rule.RightContent);
  37:         }
  38:         else
  39:         {
  40:             switch (rule.Operator.ToLowerInvariant())
  41:             {
  42:                 case "=":
  43:                 case ">":
  44:                 case ">=":
  45:                 case "<":
  46:                 case "<=":
  47:                 case "contains":
  48:                 case "<>":
  49:                 case "not contains":
  50:                     rulesXml += string.Format("\t<rule field=\"{1}\" op=\"{0}\" value=\"{2}\" />\r\n", rule.Operator, rule.LeftContent, rule.RightContent);
  51:                     break;
  52:                 case "reports under":
  53:                 case "member of":
  54:                     rulesXml += string.Format("\t<rule op=\"{0}\" value=\"{1}\" />\r\n", rule.Operator, rule.RightContent);
  55:                     break;
  56:                 case "and":
  57:                 case "or":
  58:                 case "(":
  59:                 case ")":
  60:                     rulesXml += string.Format("\t<rule op=\"{0}\" />\r\n", rule.Operator);
  61:                     break;
  62:             }
  63:         }
  64:     }
  65:     rulesXml += "</rules>";
  66:     return rulesXml;
  67: }

The help for the command is shown below:

C:\>stsadm -help gl-enumaudiencerules

stsadm -o gl-enumaudiencerules

Outputs the rules for an audience.

        -name <audience name>
        [-ssp <SSP name>]
        [-explicit (shows field and value attributes for every rule)]

The following table summarizes the command and its various parameters:

Command Name Availability Build Date
gl-enumaudiencerules MOSS 2007 8/6/2008

Parameter Name Short Form Required Description Example Usage
name n Yes The name of the audience -name "IT Department"

-n "IT Department"
ssp   No The name of the SSP that the audience is associated with.  If not specified then the default SSP is used. -ssp SSP1
explicit ex No If specified then all attributes will be returned in the XML - this is only really useful if you wish to see the field names of the special operators, "member of" and "reports under". -explicit


The following is an example of how to display the rules associated with an audience:

stsadm -o gl-enumaudiencerules -name "IT Department"

The following is an example of the XML that would be displayed:

   1: <rules>
   2:     <rule op="(" />
   3:     <rule field="Department" op="=" value="IT" />
   4:     <rule op="or" />
   5:     <rule op="reports under" value="domain\glapointe" />
   6:     <rule op=")" />
   7:     <rule op="and" />
   8:     <rule field="IsContractor" op="=" value="false" />
   9: </rules>

No comments: