As Microsoft and their certified device partners gear up to bring more native Microsoft Teams IP Phones to the market the management and customization of the device experience is also being expanded upon.  This article introduces the current capabilities of a new PowerShell cmdlet created specifically to manage the user experience of these devices.

For some time the Set-CsIPPhonePolicy cmdlet has been available in the Skype for Business Online PowerShell module, which initially only applied to Lync Phone Edition, but was later also used with 3PIP-qualified devices (like VVX phones).  That cmdlet only controls a single globally-applicable set of parameters though, so it was not possible to create different sets of behaviors which could be applied to different groupings of phones.

With Microsoft Teams a new cmdlet named Set-CsTeamsIPPhonePolicy has been introduced, which is still included in the Skype for Business Online PowerShell module alongside all other Teams platform administrative cmdlets.  At the time of posting this article Microsoft has not yet published any official documentation for this cmdlet, but the functionality is already present in Office 365 tenants.

The most obvious change between the Skype IP Phone functionality and the what now exists for Teams devices is there is also a New-CsTeamsIPPhonePolicy cmdlet which allows the creation of custom policies in addition to the default global policy (which can be modified if desired).  This addresses a long overdue customer request to assign unique parameter values to different categories of phones, be it by location, department, use-case, etc.  Alongside this cmdlet is the requisite Grant-CsTeamsIPPhonePolicy cmdlet which is used to assign custom policies to individual user accounts.

Currently there is a very limited set of parameters available to actually control phone behavior, but the groundwork has been laid to start defining unique policies and then assigning these polices to user accounts to control their IP phone experiences.

Investigating the New Cmdlets

To take a closer look at this new capability launch PowerShell and import the Skype for Business Online module (if installed) as outlined in numerous articles like this.  Then list out the available cmdlets in the imported module that match the ‘TeamsIPPhone’ naming scheme.

• Launch PowerShell and connect to Skype for Business Online using an account which sufficient administrative rights in the desired tenant.

Import-Module SkypeOnlineConnector
$sfbo = New-CsOnlineSession -UserName jeff@msteams.net
Import-PSSession $sfbo

• Enter the following command to list all available cmdlets matching the desired string.  Take note that the name of the module is dynamic and will be unique for every imported session, so use the name shown after successfully importing the Skype module (e.g. tmp_iwwu1ido.jpc).

Get-Command -Module tmp_iwwu1ido.jpc | Where-Object {$_.Name -like “*TeamsIPPhone*”}

The results should look like the following:

The five new cmdlets could logically be grouped as:

• [Get|Set]-CsTeamsIPPhonePolicy – used to review and modify the parameters of an existing global or user policy.

• [New|Remove]-CsTeamsIPPhonePolicy – used to create and delete user policies.

• Grant-CsTeamsIPPhonePolicy – used to assign users to a specific user policy which will override the Global policy’s behavior.

Notice that there is no companion cmdlet for the ‘Grant-’ cmdlet.  This is because, like all other Skype and Teams policy-related cmdlets, the process to remove a user from an assigned user policy is simply to run the same cmdlet again, but instead assign the user to a $null policy.  Users can only be assigned to user policies and cannot explicitly be assigned to a global policy; assigning them to a null policy will return them to the default behavior of adhering to the global policy.

The next step into investigating the configuration would be to take a look at the default Global policy.

• Run the Get-CsTeamsIPPhonePolicy cmdlet to list all defined policies and their current settings.

Get-CsTeamsIPPhonePolicy

The default configuration in all Office 365 tenants should simply return a single Global policy with the parameters shown above.  As previously mentioned, the list of configurable parameters in these policies are currently quite limited.  In fact, at the time this article was written there are only two behaviors which can be controlled: the primary client experience via the sign in mode, and the inclusion of the Search function on Common Area Phones.

As best practices typically dictate it is generically recommended to leave the default global parameters as they are and create new user policies to customize any behavior.  Be aware that the only available policy types here are global and user, so if there is a behavior which would be deemed desirable for all users then it would be easier to manage this change at the global level then having to manually add every new user account in the tenant to a specific user policy.  This would likely become more applicable if/when future parameters are added here that make sense to modify at a tenant-wide level, as the available settings are not really good candidates for a tenant-wide change.

Now that some parameter values have been discovered the piece to uncover is what are the possible configuration options for these settings?  A simple way to find that out in PowerShell is to attempt to set a parameter to an obviously invalid value and when the cmdlet fails the error response will return the list of accepted values.

• Run the Set-CsTeamsIPPhonePolicy cmdlet using a bogus value (e.g. NotARealParameterValue) for the SignInMode parameter

Set-CsTeamsIPPhonePolicy -SignInMode “NotARealParameterValue”

This invalid command has returned a list of possible values for the parameter which includes UserSignIn, CommonAreaPhoneSignIn, and MeetingSignIn.

• Run the same command as above, but against the SearchOnCommonAreaPhoneMode parameter.

Set-CsTeamsIPPhonePolicy -SearchOnCommonAreaPhoneMode “NotARealParameterValue”

This parameter is a simple ‘on/off’ switch as the only possible values are Enabled or Disabled.

Sign In Mode

What the SignInMode parameter controls is essentially the overall user experience on the Teams device Android client.  There are three different options which provide three unique interfaces targeted at three specific, common use-cases: regular users, shared meeting rooms, and common areas.  The available parameter values are as follows:

UserSignIn

The UserSignIn setting provides the full client experience which is typically targeted for regular phone users.  Unless any changes are applied to the tenant using the cmdlets and guidance in this article then all user accounts signing into all Teams IP phones will receive this experience as the default global policy is set to this value.

The latest phone software no longer prompts the user during sign-in to select if they want a Personal or Shared experience (as outlined in a past article).  The account type which is signing into the phone does not matter, so whether it is a user mailbox or room mailbox or if it has been enabled in Skype for Business using the CsMeetingRoom cmdlet set is irrelevant.  Additionally, the type of Office 365 license applied to the account has no effect here either.  Thus, an account configured as a room mailbox and assigned a Common Area Phone license (which is a bad idea for other reasons) will still show the full client experience when signing into a Teams phone in this example tenant based on the fact that only the single global policy exists which is set to UserSignIn mode.  In short, the overall client experience is controlled only by this PowerShell policy, and nothing else.

This mode provides the full client experience which includes the Calls, Calendar, and Voicemail screens, the Search button, the Call Park button, and the New Meeting/New Call buttons, as shown in the following screenshots from a Poly CCX 600 phone.

Calls

Calendar

Voicemail

Note that the screenshots above are using the Dark Theme option, which is not the default appearance. Once a user signs into a phone then they can enable Dark Theme directly from within the client’s Settings menu; this is not a setting which is currently controllable by an administrator.

MeetingSignIn

This setting is meant to be used on phones which are located in conference rooms where the primary use case is joining scheduled meetings.  In order to utilize this mode on a phone a new user policy must be created so that it can be assigned to the user account which will be signed into the phone.

• Using the New-CsTeamsIPPohnePolicy cmdlet create a new user policy and configure the sign in mode for meeting devices.

New-CsTeamsIPPhonePolicy -Identity “MR” -Description “Meeting Room Phone User Policy” -SignInMode MeetingSignIn

• Assign the new meeting room policy to the desired user account.

Grant-CsTeamsIPPhonePolicy -PolicyName “MR” -Identity “trio8500@msteams.net”

When logging into a Teams phone using this account the interface will default to showing only the Calendar view, and the Dial button if the account is Enterprise Voice enabled with the requisite Phone System licensing.  Some of the available options in the client are hidden from the user, like the Sign Out menu item has been relocated to the Settings > Device Settings > Admin Only menu which is password-protected.  The Search button is still available, but the Call Park button has been removed.

The following screenshots where taken from a Poly Trio 8500 using the account which was added to the Meeting Room policy in the previous steps.  For comparison’s sake images from both the default theme and dark theme are shown below.

CommonAreaPhoneSignIn

This setting provides to most restrictive user experience intended for phones in common areas which may even be placed in public area.  In order to utilize this mode on a phone another new user policy should be created so that it can be assigned to other user accounts.

• Using the New-CsTeamsIPPohnePolicy cmdlet create a new user policy and configure the sign in mode for common area devices.

New-CsTeamsIPPhonePolicy -Identity “CAP” -Description “Common Area Phone User Policy” -SignInMode CommonAreaPhoneSignIn –SearchOnCommonAreaPhoneMode Disabled

The SearchOnCommonAreaPhoneMode parameter can be set to either Enabled or Disabled, whichever is preferred.

• Assign the new common area policy to the desired user account.

Grant-CsTeamsIPPhonePolicy -PolicyName “CAP” -Identity “ccx400@msteams.net”

When logging into a Teams phone using this account the only the dial pad will be displayed along with the Call Park button. The Search function can selective be hidden or shown via the other setting in the policy.

• To allow the Search function to be used on Common Area Phones simply modify the newly created user policy to enable that feature.

Set-CsTeamsIPPhonePolicy -Identity CAP -SearchOnCommonAreaPhoneMode Enabled

Once the policy change is picked up by the phone it should display the Search button.

Review Configuration

• To view the existing policy configuration simply run the Get-CsTeamsIPPhonePolicy cmdlet to list all defined policies and their current parameter values.

Get-CsTeamsIPPhonePolicy

• To quickly check which users have been assigned to a user policy run the following command to list all users in the tenant, showing only the User Principal Name (UPN) and TeamsIPPhonePolicy parameters.  (Users with no value set for the phone policy will adhere to the Global policy.)

Get-CsOnlineUser | ft UserPrincipalName, TeamsIPPhonePolicy