Haiku #193

If a tree falls in

The forest then it's his fault.

Device update rules.

 

Here's something that will shock you: the author of today's haiku is a cold-blooded killer.

 

Note. Really? OK. We just thought that would shock you.

 

As it turns out, yesterday the author of today's haiku printed out a one-page checklist of things he needs to look into for an upcoming documentation project. When he went to pick up his one page (front and back) checklist, the cover sheet attached to the printout included this blood-curdling message:

 

You just killed a tree

 

As you might expect, the author of today's haiku was stunned to hear that he had just killed a tree. After all, the author of today's haiku has always fancied himself something of a conservationist, and has always been a dedicated recycler. For example, back when his son used to get action figures for Christmas, the author of today's haiku would dutifully tear apart the packaging for those action figures, tossing out the plastic, but recycling the cardboard. For someone like that to kill a tree, well, that wasn't exactly the best news he got all day.

 

Note. OK, actually that was the best news he got all day. But that's another story.

 

So how can the author of today's haiku defend himself? Well, truthfully, he can't: after all, he did click the Print button. Still, he did only use up a single piece of paper (the same amount of paper required for the cover sheet). And he does wonder this: if it takes an entire tree to make one piece of paper, shouldn't we maybe look for a different paper supplier? But no excuses: what's done is done.

 

To make matters even worse, this isn't the first time he's been accused of killing trees. Every month when he gets his bill from the cable company, that bill includes a memo noting that he could have saved a tree by switching to electronic billing. That bill also includes a ton of advertisements for other services the cable company offers but that the author of today's haiku has yet to sign up for. The bill also includes flyers for the cable company's on-demand service (because the author of today's haiku is likely to be thinking, "I demand to see Shark 3D, right now!) and for upcoming pay-per-view extravaganzas like WrestleMania (can you believe we're up to WrestleMania XVII already; where does the time go?) and the next UFC championship bout (Quinton "Rampage" Jackson vs. Anne Hathaway). The author of today's haiku isn't trying to justify the fact that he killed a tree by not switching to electronic billing; he's just wondering how many trees the cable company killed by including all that wasted paper in his bill?

 

Note. Ah, good point: maybe the cable company is holding him (or, more correctly, the trees) hostage. "Switch to electronic billing now or we start killing the hostages one-by-one."

 

And no, the author of today's haiku would never put anything past the cable company.

 

But enough about that. By now you're probably wondering, "So what does the author of today's haiku do when he isn't singlehandedly deforesting the world?" And here's your answer: he uses the CsDeviceUpdateRule cmdlets (Approve-CsDeviceUpdateRule, Get-CsDeviceUpdateRule, Remove-CsDeviceDeviceRule, Reset-CsDeviceUpdateRule, and Restore-CsDeviceUpdateRule) to manage the device update service.

 

Hey, even cold-blooded killers need to have a hobby, right?

 

So what's so great about the CsDeviceUpdateRule cmdlets? Two things. First, they're environmentally-friendly: even the author of today's haiku rarely kills a tree when running these cmdlets. (Hey, we said rarely.) Perhaps more important, they serve a very useful function when it comes to managing Microsoft Lync Server 2010.

 

And what is that useful function? Well, as you know (because you did read Haiku #145, didn't you?) Lync Server uses the device update service to provide a way to push firmware updates to devices that run Microsoft Lync Phone Edition. These firmware updates are periodically published by Microsoft, and administrators can easily get a copy of the updates and then upload the update files to Lync Server. From there, the updates can then be distributed to the appropriate phones and devices.

 

You know, that's a good point: there have been times when updates have created more problems than they solved, haven't there? But don't worry: the Lync Server product team already thought of that. When you upload your device update "rules" (a rule is simply an update for a particular type of device, such as LG-Nortel cell phones) each rule is marked as being in a Pending state. When a rule is marked as Pending, that means it does not get pushed out to all the relevant devices. Instead, the update is only installed on predefined test devices. After administrators have verified that the update is working properly on the test devices then the update rule can be marked as being Approved. That update will then be automatically downloaded and installed on all the relevant devices (for example, all the LG-Nortel cell phones).

 

So how does a device update rule get approved? Why, by calling the Approve-CsDeviceUpdateRule cmdlet, of course:

 

Approve-CsDeviceUpdateRule -Identity service:WebServer:atl-cs-001.litwareinc.com/d5ce3c10-2588-420a-82ac-dc2d9b1222ff9

 

Admittedly, that's an … interesting … little command. (Please don't print it out; the author of today's haiku has killed enough trees as it is.) The problem, as you can see, is that each device update rule has an Identity that consists of the Web server the rule was imported to plus a GUID (globally unique identifier). That makes it easy to uniquely pinpoint a given rule, but somewhat less easy to actually type in a command that approves that rule.

 

But don't despair: with clever use of the Get-CsDeviceUpdateRule cmdlet you can typically avoid having to work with rule Identities. For example, suppose you have only one update rule that refers to LG-Nortel phones. Perfect; that means you can use a command like this to retrieve (and approve) that rule:

 

 Get-CsDeviceUpdateRule | Where-Object {$_.Brand -eq "LG-Nortel"} | Approve-CsDeviceUpdateRule

 

That's a little bit easier, to say the least. And if you need to get a little fancier (say you only want to approve a specific model of the LG-Nortel phone), well, then just get a little fancier:

 

 Get-CsDeviceUpdateRule | Where-Object {$_.Brand -eq "LG-Nortel" –and $_.Model –eq "IP8540"} | Approve-CsDeviceUpdateRule

 

With the Get-CsDeviceUpdateRule cmdlet you can filter on such things as:

 

· Device type (typically UCPhone)

· Brand

· Model

· Revision

· Locale

· UpdateType

· ApprovedVersion

· RestoreVersion

· PendingVersion

 

Pretty cool, huh?

 

As we noted, when you first upload device update rules each rule is marked as Pending; that simply means that the rule version number will be assigned to the PendingVersion property:

 

ApprovedVersion :

RestoreVersion :

PendingVersion : 4.0.7168.0

 

When you approve a rule, that version number gets assigned to the ApprovedVersion property and the PendingVersion is set to a Null value:

 

ApprovedVersion : 4.0.7168.0

RestoreVersion : 4.0.6991.0

PendingVersion :

 

So how do you get a list of rules that have been approved? Like this:

 

Get-CsDeviceUpdateRule | Where-Object {$_.ApprovedVersion –ne $Null}

 

In other words, if a rule has been approved then the ApprovedVersion property will be equal to something.

 

And to get a list of rules still in the Pending state? You got it:

 

Get-CsDeviceUpdateRule | Where-Object {$_.PendingVersion –ne $Null}

 

That just leaves us with the RestoreVersion property and, by extension, the Reset-CsDeviceUpdateRule cmdlet and the Restore-CsDeviceUpdateRule cmdlet. (We're going to take it on faith that you've already figured out that the Remove-CsDeviceUpdateRule cmdlet removes a device update rule.)

 

Let's start off by talking about what the Reset-CsDeviceUpdateRule cmdlet does. As we noted earlier, each device update rule begins life by being marked as Pending; as we also noted, that enables administrators to test the update before making it available to users. If the update seems to be working then administrators can mark the update as approved.

 

Ah, but suppose the update is not working. In that case, administrators can run the Reset-CsDeviceUpdateRule cmdlet against that rule:

 

 Get-CsDeviceUpdateRule | Where-Object {$_.Brand -eq "LG-Nortel"} | Reset-CsDeviceUpdateRule

 

What's the point of that? Well, when you do that, the value of the PendingVersion property gets set to null:

 

ApprovedVersion:

RestoreVersion:

PendingVersion:

 

And what's the point of that? Well, when PendingVersion is set to null, the update in question will be uninstalled from the test devices; in addition, the test devices will re-install their most recently-approved update. With PendingVersion set to null test devices won't bother with the update. And with ApprovedVersion set to null, user devices woin't bother with the update, either.

 

Of course, PendingVersion only works with rules that are in the Pending state; that is, rules that have never been approved. Now, suppose you approve a rule and only later discover that the update is causing problems. In that case, Reset-CsDeviceUpdateRule won't do you any good; instead, you'll need to run the Restore-CsDeviceUpdateRule cmdlet instead:

 

 Get-CsDeviceUpdateRule | Where-Object {$_.Brand -eq "LG-Nortel"} | Restore-CsDeviceUpdateRule

 

So what does that command do? Well, we kind of skipped over this earlier, but when you approve a device update rule three things actually happen: 1) the PendingVersion is set to a null value; 2) the ApprovedVersion is set to the version of the newly-approved update rule; and, 3) the RestoreVersion is set to the version number of the rule that was previously-approved for this device. Remember this output:

 

ApprovedVersion : 4.0.7168.0

RestoreVersion : 4.0.6991.0

PendingVersion :

 

That output tells us that, prior to approving rule 4.0.7168.0, we had approved rule 4.0.6991.1.

 

Why do we care about the previously-approved rule? Well, we've just discovered that our new rule (rule 4.0.7168.0) doesn't work. If we run the Restore-CsDeviceUpdateRule cmdlet here's what happens:

 

ApprovedVersion : 4.0.6991.0

RestoreVersion :

PendingVersion :

 

See? What Restore-CsDeviceUpdateRule does is take the old rule and make that old rule (4.0.6991.0) the ApprovedVersion. What difference does that make? Well, that will cause all the affected devices to uninstall update 4.0.7168.0 and reinstall 4.0.6991.0. In other words, we put things back the way they were before we installed the update.

 

Note. And if there is no previous version? That's fine. In that case, the "bad" update will simply be uninstalled.

 

Got all that? Admittedly, it's a little complicated, at least at first glance. But it's actually a pretty good system, and it even makes sense once you think about it a bit.

 

Really.

 

See you tomorrow.

 

Note. No trees were harmed in the making of today's haiku. However, a rhododendron did lose a few leaves, and a morning glory got its feelings hurt a little. The authors of the Lync Server PowerShell blog deeply regret both of these incidents.