New-CsPushNotificationConfiguration

 

Topic Last Modified: 2012-04-23

Creates a new collection of push notification configuration settings at the site scope. The push notification service (Apple Push Notification Service and Microsoft Lync Server 2010 Push Notification Service) provides a way to send notifications about events such as new instant messages or new voice mail to mobile devices such as iPhones and Windows Phones, even if the Microsoft Lync 2010 application on those devices is currently suspended or running in the background.

Syntax

New-CsPushNotificationConfiguration -Identity <XdsIdentity> [-Confirm [<SwitchParameter>]] [-EnableApplePushNotificationService <$true | $false>] [-EnableMicrosoftPushNotificationService <$true | $false>] [-Force <SwitchParameter>] [-InMemory <SwitchParameter>] [-Tenant <Nullable>] [-WhatIf [<SwitchParameter>]]

Detailed Description

The Apple Push Notification Service and the Microsoft Lync Server 2010 Push Notification Service enable users running Lync 2010 on their Apple iPhone or Windows Phone to receive notifications about Lync 2010 events even when Lync 2010 is suspended or running in the background. For example, users can receive notice for events such as these:

- Invitations to a new instant messaging session or conference

- New instant messages

- New voice mail

Without the push notification service, users would receive these notices only when Lync 2010 was in the foreground and serving as the active application.

Administrators have the ability to enable or disable push notifications for iPhone users and/or Windows Phone users. (By default, push notifications are disabled for both iPhone users and Windows Phone users.) Administrators can enable or disable push notifications at the global scope by using the Set-CsPushNotificationConfiguration cmdlet. They can also create custom push notification settings at the site scope by using the New-CsPushNotificationConfiguration cmdlet. That gives Administrators the ability to provide push notifications to users in some sites (for example, Redmond) while restricting the use of these notifications in other sites.

Who can run this cmdlet: By default, members of the following groups are authorized to run the New-CsPushNotificationConfiguration cmdlet locally: RTCUniversalServerAdmins.

Parameters

Parameter Required Type Description

Identity

Required

XdsIdentity

Push notification settings can only be created at the site scope. To specify a new collection of settings for a site, use syntax similar to this:

-Identity "site:Redmond"

Note that this command will fail if the Redmond site already hosts a collection of push notification settings.

EnableApplePushNotificationService

Optional

Boolean

When set to True, iPhone users will receive push notifications from the Apple Push Notification Service. When set to False, iPhone users will not receive these notifications.

The default value is False.

EnableMicrosoftPushNotificationService

Optional

Boolean

When set to True, Windows Phone users will receive push notifications from the Microsoft Lync Server 2010 Push Notification Service. When set to False, Windows Phone users will not receive these notifications.

The default value is False.

Tenant

Optional

GUID

This parameter is reserved for use with Microsoft Office 365.

InMemory

Optional

SwitchParameter

Creates an object reference without actually committing the object as a permanent change. If you assign the output of a command called with this parameter to a variable, you can make changes to the properties of the object reference and then commit those changes by calling this cmdlet’s matching Set- cmdlet.

Force

Optional

SwitchParameter

Suppresses the display of any non-fatal error message that might occur when running the command.

WhatIf

Optional

SwitchParameter

Describes what would happen if you executed the command without actually executing the command.

Confirm

Optional

SwitchParameter

Prompts you for confirmation before executing the command.

Input Types

None. New-CsPushNotificationConfiguration does not accept pipelined input.

Return Types

New-CsPushNotificationConfiguration creates new instances of the Microsoft.Rtc.Management.WriteableConfig.Settings.PushNotificationConfiguration.PushNotificationConfiguration object.

Example

-------------------------- Example 1 --------------------------

New-CsPushNotificationConfiguration -Identity "site:Redmond" -EnableApplePushNotificationService $True -EnableMicrosoftPushNotificationService -$True

The command shown in Example 1 creates a new collection of push notification settings for the Redmond site, and enables push notifications from both the Apple Push Notification Service and the Microsoft Lync Server 2010 Push Notification Service. The latter is done by setting both the EnableApplePushNotificationService and the EnableMicrosoftPushNotificationService properties to True.

-------------------------- Example 2 --------------------------

Get-CsSite | ForEach-Object {New-CsPushConfigurationNotification -Identity $_.Identity}

Example 2 shows how you can create a set of push configuration settings for each of your Lync Server sites. To do this, the command first uses Get-CsSite to return a collection of all your Lync Server sites. That collection is then piped to the ForEach-Object cmdlet, which takes each site in the collection, calls New-CsPushNotificationConfiguration, and creates a new set of push notification configuration settings for that site. Note that this command will fail for any site that already hosts a collection of push notification configuration settings.

-------------------------- Example 3 --------------------------

$x = New-CsPushNotificationConfiguration -Identity "site:Redmond" -InMemory
$x.EnableApplePushNotificationService = $True 
$x.EnableMicrosoftPushNotificationService = $True
Set-CsPushNotificationConfiguration -Instance $x

The preceding example demonstrates the use of the InMemory parameter to create a collection of push notification configuration settings that initially exist only in memory. To do this, the example creates a new collection of settings (with the Identity site:Redmond) and stores this collection in a variable named $x. Note that, after this first command executes, the collection exists only in memory; if you run the command Get-CsPushNotificationConfiguration you will not see an entry for site:Redmond.

In the next two commands, both the EnableApplePushNotificationService and the EnableMicrosoftPushNotificationService properties for this virtual collection of settings are set to True, which enables push notifications from both the Apple Push Notification Service and the Microsoft Lync Server 2010 Push Notification Service. Finally, the last command uses Set-CsPushNotificationConfiguration to transform the virtual push notification settings into an actual collection of settings applied to the Redmond site. If you do not call Set-CsPushNotificationConfiguration, these settings will remain in memory only and will disappear when your Windows PowerShell session is terminated or the variable $x is deleted.