[This is preliminary documentation and is subject to change. Blank topics are included as placeholders.]

Returns information about the Microsoft Communications Server 2010 announcements configured for use in your organization. Announcements are played when users dial a valid but unassigned phone number. With announcements, users who dial one of these numbers can be given a message (such as "This number is temporarily out of service") or can be presented with a busy signal.

Syntax

Get-CsAnnouncement [-Identity <XdsIdentity>] [-LocalStore <SwitchParameter>]
Get-CsAnnouncement [-Filter <String>] [-LocalStore <SwitchParameter>]

Parameters

Parameter Required Type Description

Identity

Optional

Xds Identity

An identifier for the Announcement you want to retrieve. If you omit this parameter and the Filter parameter, all instances of announcement configured for the organization will be displayed. The value for the Identity parameter can be supplied in one of two ways:

- Enter the Identity of the Application service for the announcements you want to retrieve. This will retrieve all announcements configured with the given service Identity. For example, ApplicationServer:Redmond.litwareinc.com.

- Enter the full Identity of the single announcement you want to retrieve. This value will always be in the format <serviceID>/<GUID>, where serviceID is the Identity of the Application Server running the Announcement Service and GUID is a globally unique identifier associated with this announcement. For example: ApplicationServer:Redmond.litwareinc.com/bef5fa3b-3c97-4af0-abe7-611deee7616c.

Filter

Optional

String

This parameter allows you to perform a wildcard search on the Identity of all announcements configured for the organization. Use the wildcard character to filter on any part of the Identity.

LocalStore

Optional

SwitchParameter

Retrieves the announcement information from the local replica of the Central Management database, rather than the Central Management database itself.

Detailed Description

An enterprise can own phone numbers that are not assigned to users or phones, but which are still valid numbers that can be called. By default when someone dials one of those numbers he or she will receive a busy signal and the call may result in an error returned to the SIP client. By applying announcement settings to unassigned numbers, administrators have the option of playing a message, returning a busy signal, or redirecting the call. This cmdlet retrieves one or more of these announcement settings.

Return Types

Returns one or more instances of the Microsoft.Rtc.Management.WritableConfig.Settings.AnnouncementServiceSettings.Announcement object.

Examples

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

Copy Code
Get-CsAnnouncement

Example 1 returns all the announcements configured for use in the organization. This is done by calling Get-CsAnnouncement without any parameters.

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

Copy Code
Get-CsAnnouncement -Identity "ApplicationServer:redmond.litwareinc.com/1951f734-c80f-4fb2-965d-51807c792b90" 

The preceding command returns a single announcement: the announcement with the Identity ApplicationServer:redmond.litwareinc.com/1951f734-c80f-4fb2-965d-51807c792b90. Example 5 provides an alternate (and arguably easier) way to retrieve a specific announcement.

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

Copy Code
Get-CsAnnouncement -Identity "ApplicationServer:redmond.litwareinc.com"

The command shown in Example 3 returns information about all the announcements that have been configured for use on the service ApplicationServer:redmond.litwareinc.com.

-------------------------- Example 4 ------------------------

Copy Code
Get-CsAnnouncement -Filter "service:Redmond*"

In Example 4, information is returned for all the announcements configured for use in the Redmond site. This is done by including the -Filter parameter and the filter value "service:Redmond*", which limits the returned data to announcements that have an Identity that begins with the string value "service:Redmond". By definition, those are announcements configured for use in the Redmond site.

-------------------------- Example 5 ------------------------

Copy Code
Get-CsAnnouncement | Where-Object {$_.Name -eq "Welcome Announcement"}

Example 5 shows an alternate way to return a specific announcement; in this case, an announcement named Welcome Announcement. To do this, Get-CsAnnouncement is first called, without any parameters, in order to return a collection of all the announcements in use in the organization. This collection is then piped to the Where-Object cmdlet, which picks out those announcements that have a Name equal to (-eq) "Welcome Announcement".

-------------------------- Example 6 ------------------------

Copy Code
Get-CsAnnouncement -Identity "ApplicationServer:redmond.litwareinc.com" | Where-Object {$_.Name -eq "Welcome Announcement"}

Example 6 in similar to Example 5, but this example shows another way to return a single announcement. We once again call Get-CsAnnouncement, but this time we specify an Identity of ApplicationServer:redmond.litwareinc.com. This will return a collection of all announcements associated with that service. As in Example 5, this collection is then piped to the Where-Object cmdlet, which picks out those announcements that have a Name equal to (-eq) "Welcome Announcement". Because announcement names must be unique within an application service, this command will never return more than a single item.

-------------------------- Example 7 ------------------------

Copy Code
Get-CsAnnouncement | Where-Object {$_.Name -like "Welcome*"}

This example is similar to Example 5 in that we retrieve all the announcements, then pipe the collection of announcements to the Where-Object cmdlet. However, in Example 5 we used the –eq operator in the where clause to find an identical match for the name. In this example we’ve used the –like operator and a wildcard value to find all announcments that, in this case, begin with the string Welcome.

-------------------------- Example 8 ------------------------

Copy Code
Get-CsAnnouncement | Where-Object {($_.TextToSpeechPrompt -ne $Null) -and ($_.Language -ne "en-US")}

In Example 8, information is returned for all the announcements that use a TTS prompt but do not use US English as their primary language. To carry out this task, the command first calls Get-CsAnnouncement in order to return a collection of all the announcements currently configured. This collection is then piped to the Where-Object cmdlet, which selects all the announcements where the TextToSpeechPrompt property is not empty (not equal to $Null) and where the Language property is not equal to (-ne) en-US.