Listing the Names of the Agent Groups Assigned to a Response Group Queue
The best thing about being a technical writer at Microsoft is that you are constantly reminded how little you actually know about the technology you're charged with writing about.
Note. No, we're not being facetious: that really is the best thing about being a technical writer at Microsoft.
Hey, how do you think we feel about that?
For example, the other day we received an email from someone wondering why he couldn't use the Get-CsRgsQueue cmdlet to view the names of the agent groups assigned to a Response Group queue. Needless to say, our initial reaction was that the person who sent the email had no idea what he was talking about. "Of course you can use the Get-CsRgsQueue cmdlet to view the names of the agent groups assigned to a Response Group queue," we thought to ourselves. "After all, one of the properties returned by Get-CsRgsQueue is the AgentGroupIDList property. Are we the only people in the world who know anything at all about Microsoft Lync Server 2010?!?"
Needless to say, you can already guess where this headed. Just to prove to ourselves that we really were right, we created a new Response Group queue, created a pair of agent groups, then assigned those two agent groups to the new queue. We then ran this command in order return information about all our Response Group queues, including this newly-created queue:
Get-CsRgsQueue
And when we ran that command did we get back a value for the AgentGroupIDList property? You bet we did. See for yourself:
Identity : service:ApplicationServer:pool0.litwareinc.com/7c051be4-9dc7-435f-8ddc-b53ffcfac41 1
TimeoutAction : Action=Terminate
OverflowAction : Action=TransferToVoicemailUri
Uri=sip:+14255551298@litwareinc.com
Name : help Desk
Description :
TimeoutThreshold :
OverflowThreshold :
OverflowCandidate : NewestCall
AgentGroupIDList : {service:ApplicationServer:pool0.litwareinc.com/767a3a88-f856-4503-bb1d-cdfa6036bffd, service:ApplicationServer:pool0.litwareinc.com/368ed763-b747-4c71-bccc-68c0c7124624}
Now, you might very well be looking at this output and wondering, "Why did they give their agent groups names like service:ApplicationServer:pool0.litwareinc.com/767a3a88-f856-4503-bb1d-cdfa6036bffd?" Well, the truth is, we didn't: we actually named our agent groups Agent Group 1 and Agent Group 2. (OK, maybe not the best names in the world, but still a sight better than service:ApplicationServer:pool0.litwareinc.com/767a3a88-f856-4503-bb1d-cdfa6036bffd. So then why the weird value for the AgentGroupIDList property?
Well, as it turns out, the Get-CsRgsQueue cmdlet doesn't bring back the names of the agent groups assigned to a queue; instead, it returns the identities of those agent groups. With the Response Group application, an agent group Identity consists of the address of the Application Server where the group resides (service:ApplicationServer:pool0.litwareinc.com) plus a GUID that is automatically assigned to the group at the time it gets created (767a3a88-f856-4503-bb1d-cdfa6036bffd). Our email correspondent was right: Get-CsRgsQueue doesn't return the names of the assigned agent groups after all.
Note. So if the email correspondent was right does that mean that we were wrong? Um, we don't really have time for any more questions today. Let's keep moving, OK?
It doesn't matter who was right and who was wrong here; after all, regardless of who knew what they were talking about (and who didn't) we still had a problem: how do we get back the names of the agent groups that have been assigned to a Response Group queue? Identities like service:ApplicationServer:pool0.litwareinc.com/767a3a88-f856-4503-bb1d-cdfa6036bffd are great for computers, but not all that much fun for people to try to work with.
Well, one way we could get back the names would be to first call the Get-CsRgsAgentGroup cmdlet to get back information about all our agent groups. We could then scroll through the results, trying to match up the identities retrieved by Get-CsRgsQueue with the identities retrieved by Get-CsRgsAgentGroup. As soon as we found an agent group that has the Identity service:ApplicationServer:pool0.litwareinc.com/767a3a88-f856-4503-bb1d-cdfa6036bffd we could then check the value of the Name property and determine the name of the group. And then we could repeat the process with the next Identity returned by Get-CsRgsQueue.
And that's a great idea, except for one thing: it's actually a terrible idea. If you only have 4 agent groups you could maybe do this yourself, but what if you had to slog your away through 500 or 600 agent groups? Quick; are these two Identities a perfect match or not:
service:ApplicationServer:pool0.litwareinc.com/767a3a88-f856-4503-bb1d-cdfa6036bffd
service:ApplicationServer:pool0.litwareinc.com/767a3a88-f356-4503-bb1d-cdfa6036bffd
See what we mean? That approach could take forever.
Note. By the way, the two Identities are not a perfect match.
So is there a better way to solve this problem? Of course there is. Instead of you slogging through all the agent groups looking for a match, let Windows PowerShell do it for you:
$agentIDs = Get-CsRgsQueue -Identity service:ApplicationServer:pool0.litwareinc.com -Name "Help Desk" | Select-Object -ExpandProperty AgentGroupIDList
foreach ($myQueue in $agentIDs)
{
$service = $myQueue.ServiceID
$groupIdentity = $service.FullName + "/" + $myQueue.InstanceID
$group = Get-CsRgsAgentGroup -Identity $groupIdentity
$group.Name
}
Let's see if we can explain how this script works. In the first line we use the Get-CsRgsQueue cmdlet to retrieve the Response Group queue that has the Identity service:ApplicationServer:pool0.litwareinc.com and the Name Help Desk. We grab the information for this queue and pipe it to the Select-Object cmdlet; from there we use Select-Object's ExpandProperty parameter to "expand" the values found in the AgentGroupIDList property. That simply means that we convert all the values in the property to individual objects. When we do that, we no longer have a big, gloppy value that looks like this:
{service:ApplicationServer:pool0.litwareinc.com/767a3a88-f856-4503-bb1d-cdfa6036bffd, service:ApplicationServer:pool0.litwareinc.com/368ed763-b747-4c71-bccc-68c0c7124624}
Instead, we have two objects, one for each of the agent groups that was assigned to the queue. Those two objects get stored in a variable named $agentIDs.
Note. Yes, we did hardcode in the queue Identity and Name, didn't we? That was actually intentional; it helped us keep the script as concise and easy-to-understand as possible. Of course, that also means that, unless you go in and make changes to it, the script can only retrieve information about the Help Desk queue.
So what's the alternative? Well, we could have used a command line argument to represent the queue name:
$agentIDs = Get-CsRgsQueue -Identity service:ApplicationServer:pool0.litwareinc.com -Name $args[0] | Select-Object -ExpandProperty AgentGroupIDList
In the preceding example, we're telling PowerShell to take the first command line argument passed to the script (that's what $args[0] represents) and use that for the queue name. That means we have to start our script by including the appropriate queue name as a command-line argument:
C:\Scripts\AgentGroupList.ps1 "Help Desk"
If you have multiple instances of the Response Group application you can also use a command line argument to represent the Identity:
$agentIDs = Get-CsRgsQueue -Identity $Args[0] -Name $args[1] | Select-Object -ExpandProperty AgentGroupIDList
Of course, we then have to include both the Identity and the Name when starting the script:
C:\Scripts\AgentGroupList.ps1 "service:ApplicationServer:pool0.litwareinc.com" "Help Desk"
But we digress. (Somewhat out of character for us, we know, but ….) After we've stashed the agent group identities in the variable $agentIDs we next set up a foreach loop to loop through each of those IDs. The first thing we do inside the loop? Why, we execute these two lines of code, of course:
$service = $myQueue.ServiceID
$groupIdentity = $service.FullName + "/" + $myQueue.InstanceID
As we noted, our agent IDs are stored in the variable $agentIDs. However, we don't really have the IDs per se; instead, we have a pair of objects that have property values like these:
ServiceId |
InstanceID |
NonNormalized |
service:ApplicationServer:pool0.litwareinc.com |
767a3a88-f856-4503-bb1d-cdfa6036bffd |
767a3a88-f856-4503-bb1d-cdfa6036bffd |
service:ApplicationServer:pool0.litwareinc.com |
368ed763-b747-4c71-bccc-68c0c7124624 |
368ed763-b747-4c71-bccc-68c0c7124624 |
With that in mind, what we're doing in the first two lines of code is combining the FullName of the ServiceID property, a slash (/) and the InstanceID property to form a real agent Identity, one that looks like this:
service:ApplicationServer:pool0.litwareinc.com/767a3a88-f856-4503-bb1d-cdfa6036bffd
Now that we've constructed the Identity (stored in the variable $groupIdentity) we can use this line of code to retrieve the Response Group agent group that has that Identity:
$group = Get-CsRgsAgentGroup -Identity $groupIdentity
At this point we echo back the group Name, then loop around and repeat the process with the next agent group in our collection.
The net result? We get the names of the agent groups associated with the Help Desk queue:
Agent Group 1
Agent Group 2
Which is all we ever wanted to see in the first place.
Now, that works pretty well for a single Response Group queue. But what if you wanted to get back a list of the agent groups that have been assigned to all your Response Group queues? Can PowerShell do something like that, too?
Do you even need to ask? We won't bother explaining how this next script works, but we will tell you that it returns a collection of all your Response Group queues as well the names of all the agent groups assigned to those queues. Give it a try and see for yourself:
$allQueues = Get-CsRgsQueue
foreach ($queue in $allQueues)
{
$agentID = Get-CsRgsQueue -Identity $queue.Identity | Select-Object -ExpandProperty AgentGroupIDList
$queue.Name
foreach ($myQueue in $agentID)
{
$service = $myQueue.ServiceID
$groupIdentity = $service.FullName + "/" + $myQueue.InstanceID
$group = Get-CsRgsAgentGroup -Identity $groupIdentity
Write-Host " ", $group.Name
}
Write-Host
}
Here's one more for the road. What we've done up till now is take a Response Group queue and find out which agent groups have been assigned to that queue. But what if we wanted to take the opposite tack: suppose we have the name of an agent group and we'd like to see which queues (if any) that group has been assigned to. What then? Well, then we could run a script like this one:
$group = Get-CsRgsAgentGroup -Name "Group No. 2"
$allQueues = Get-CsRgsQueue
foreach ($queue in $allQueues)
{
if ($queue.AgentGroupIDList -contains $group.Identity)
{
$queue.Name
}
}
Again, we won't bother to explain how this one works, at least not today; if you have questions, email us at cspshell@microsoft.com and we'll see what we can do to answer them. After all, we do know pretty much everything there is to know about Lync Server.
Pretty much.