Deep Dive into the Set-CsPinSendCAWelcomeMail Cmdlet

We are rolling out a big dial-in conferencing project. As a good percentage of our users are not yet enabled for Enterprise Voice we are doing a lot of discussing and testing about how to get those users their PIN numbers.

Without a LineURI defined, setting a PIN can be a challenge. Check these articles for more detail: LyncBuilder (via Wayback Machine…) or ExpertsExchange We have 2 options that we can think of:

1.) We could rip their defined phone number out of AD and assign that as their LineURI. Then they can go to the dialin page and set their own PIN. The problem here is that there is no guarantee that the number in AD is accurate, valid, and/or properly formatted. Even with EV disabled on an account, as soon as you set LineURI you can right click on a non-EV user and a pop out becomes available to call their work number. This should work fine but again, who knows if AD is accurate, has a valid number defined, and has that number in e.164 format.  Plus this could add some confusion when we do get around to EV enabling the user. Since they already have a lineURI, do we overwrite it? Probably, but….confusion.

2. Assign a random PIN to those users and e-mail it to them. Fortunately, there is a poorly documented Lync PowerShell command that actually does this: Set-CsPinSendCAWelcomeMail. This cmdlet is so neglected it doesn’t even get a proper Technet page like every other cmdlet does. Fortunately, it’s a fairly self explanatory cmdlet. In it’s shortest form, you can generate a random PIN for a user and then send them an e-mail with that PIN using the following syntax:

Set-CsPinSendCAWelcomeMail -UserURI cdiaz@flinchbot.com -from flinchbot@flinchbot.com -smtpserver exchange13.flinchbot.com

The UserURI is the user’s sip address without the “sip:” part. The Set-CsPinSendCAWelcomeMail does a few lookups to find a Lync user that matches this address. Note that if you just use the SamAccountName (cdiaz) or provide a SIP address (sip:cdiaz@flinchbot.com) that the cmdlet will be unable to send the e-mail. (I learned this the hard way!). I haven’t tested to see what happens if the e-mail address does not match the users SIP address but I bet the -UserEmailAddress parameter comes in handy in this case.

The -from field is the usual from field used in e-mail. Set this to an administrative account so when people receive the e-mail it will look “official” instead of coming from some doofus like me. Finally you provide the name of the mail server through which to send the e-mail with the -smtpserver parameter. So far so simple. And I bet you can figure out most of the other parameters pretty easily.

The one that took me some time to figure out is the “-TemplatePath” parameter. What this parameter does is let you pick an alternate e-mail message template than the default one that ships with Lync.

Oh, there is a default one?

This is what the default e-mail looks like. I don’t particularly like the verbiage on the first line because I think it’s wrong. Just because you have a PIN doesn’t mean you can suddenly join conferences. You can join conferences without a PIN.   Check out this folder on your Lync server: C:\Program Files\Common Files\Microsoft Lync Server 2013\Modules\Lync

Check out this folder on your Skype for Business server: C:\Program Files\Common Files\Skype for Business Server 2015\Modules\SkypeForBusiness

Inside there is a file called “CAWelcomeEmailTemplate.html”. Open it in Notepad or some other text/HTML editor and take a look. It’s all just basic HTML but I do want to point out that there are 2 variables in this file. If you want to create your own custom templates, you might need to use these:

%URL% – This is the URL to your dial in Simple URL

%PIN% – This is the PIN that was set by the cmdlet

If you only want to make a minor change, feel free to back up the original CAWelcomeEmailTemplate and then edit that one directly. Note that this directory has the annoying security set on it so you need to open your editor as Administrator in order to save back your changes. Also keep in mind that if you have multiple front ends, you’ll have to copy this edited default file to each one of your servers. And then don’t forget to do it when bringing up a new Front End in the future.

After editing the file, I ran Set-CsPinSendCAWelcomeMail again and this is the new message: Now if you want to have a separate template, or want to leave the default template alone, you need to use the -TemplatePath parameter. You can’t just copy your changed template into the C:\Program Files\Common Files\Microsoft Lync Server 2013\Modules\Lync directory and just provide the name of your new template. That would be easy. No, you have to provide a full path  (or have the file sitting in your local home folder (i.e. %userprofile% directory)). I suppose there is an advantage to this. Instead of having to copy a file to every front end, you only need to keep it in one location. Anyway, here is the command from above but this time run with the -TemplatePath parameter:

Set-CsPinSendCAWelcomeMail -UserURI cdiaz@flinchbot.com -from flinchbot@flinchbot.com -smtpserver exchange13.flinchbot.com-TemplatePath "c:\temp\MyWelcomeTemplate.html"

When running it, you get something like the following: I hope you read that whole e-mail. Partially because any reference to The Hitchhikers Guide to the Galaxy ought to be read, but mostly for the last few words: “Your PIN has not been changed”. If a user already has a PIN, then this command will not change it.

How to tell if a user already has a PIN: Run Get-CsClientPinInfo -identity <user>. 

So what can you do if you want to use this command but also want to change the PIN no matter what? You can append the -force switch to the command. So running this bad boy produces the output below:

Set-CsPinSendCAWelcomeMail -UserURI cdiaz@flinchbot.com -from flinchbot@flinchbot.com -smtpserver exchange13.flinchbot.com-TemplatePath "c:\temp\MyWelcomeTemplate.html" -force

Check out the very bottom and you can see that a random PIN was generated.

If you run this cmdlet, doesn’t it seem more like a script than just a cmdlet? That’s because it is a script. Look in this directory:

Lync:  C:\Program Files\Common Files\Microsoft Lync Server 2013\Modules\Lync

Skype: C:\Program Files\Common Files\Skype for Business Server 2015\Modules\SkypeForBusiness

There is a file called SetCsPinSendCAWelcomeMail.ps1. This is the script that actually does all the magic. It’s a really straightforward script. I’m not sure what you might want to edit in it except perhaps defining your own variables like %PIN% and %URL% that you want to add yourself.

There may be one reason that you actually do want to edit this script and that is because the verbose mode is “broken”. Lync MVP Pat Richard even opened an IdeaScale entry for this “feature”. Hacking this file will provide a workaround until Microsoft decides to update this file.

Open the file and remove every occurrence of “-Verbose:$Verbose”.  According to TechNet, -verbose “displays any verbose messages, regardless of the value of the $VerbosePreference variable.” And by default, $VerbosePreference is set to “SilentlyContinue” which means “don’t show verbose messages”