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

Creates a new dial plan.


New-CsDialPlan -Identity <XdsIdentity> [-City <String>] [-Confirm [<SwitchParameter>]] [-CountryCode <String>] [-Description <String>] [-DialinConferencingRegion <String>] [-ExternalAccessPrefix <String>] [-Force <SwitchParameter>] [-InMemory <SwitchParameter>] [-NormalizationRules <PSListModifier>] [-OptimizeDeviceDialing <$true | $false>] [-SimpleName <String>] [-State <String>] [-WhatIf [<SwitchParameter>]]


Parameter Required Type Description




A unique identifier designating the scope (global), the scope and name (site, service), or the name (per user) to identify the dial plan. For example, a site Identity would be entered in the format site:<sitename>, where sitename is the name of the site. A per-user Identity would be entered simply as a unique string value.




The city served by this dial plan. This property is used for conferencing; it is not needed for Enterprise Voice.




Prompts you for confirmation before executing the command.




The country code of the country served by this dial plan. This property is used for conferencing; it is not needed for Enterprise Voice.




A description of this dial plan--what it’s for, what type of user it applies to, or any other information that would be helpful in identifying the purpose of the dial plan.

Maximum charaters: 512




The name of the region associated with this dial plan. Available regions can be retrieved by calling the Get-CsNetworkRegion cmdlet.

Maximum characters: 512




A number (or set of numbers) that designates the call as external to the organization. (For example, to dial an outside line, first press 9.) This prefix will be ignored by the normalization rules, although these rules will be applied to the rest of the number. This prefix is applicable only to off-hook (from a phone, not from Communicator) dialing.

The OptimizeDeviceDialing parameter must be set to True for this value to take effect.

This parameter must match the regular expression [0-9]{1,4}. This means it must be a value 0 through 9, one to four digits in length.

Default: 9




Creates an object reference without actually committing the object as a permanent change. If you assign the output of this cmdlet 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.




A friendly name for the dial plan. This name must be unique among all dial plans within the Communications Server deployment.

This string can be up to 256 characters long. Valid characters are alphabetic or numeric characters, hyphen (-), dot (.), plus (+), underscore (_), and parentheses (()).

This parameter must contain a value. However, if you don’t provide a value in the call to New-CsDialPlan, a default value will be supplied. The default value for a Global dial plan is Prefix All. The default for a site-level dial plan is the name of the site. The default for a service is the name of the service (Registrar or PSTN Gateway) followed by an underscore, followed by the service fully qualified domain name (FQDN). For example, Registrar_pool0.litwareinc.com. The default for a per user dial plan is the Identity of the dial plan.




A list of normalization rules that are applied to this dial plan.

While this list and these rules can be created directly with this cmdlet, it is recommended that you create the normalization rules with the New-CsVoiceNormalizationRule cmdlet, which creates the rule and assigns it to the specified dial plan.

Each time a new dial plan is created, a new voice normalization rule is also created for that site, service, or per-user dial plan. By default the Identity of the new voice normalization rule is the dial plan Identity followed by a slash followed by the name Prefix All. For example, site:Redmond/Prefix All.

Default: {Description=;Pattern=^(\d11)$;Translation=+$1;Name=Prefix All;IsInternalExtension=False } Note: This default is only a placeholder. For the dial plan to be useful you should either modify the normalization rule created by the dial plan or create a new rule for the site, service, or user. You can create a new normalization rule by calling the New-CsVoiceNormalizationrule cmdlet; modify a normalization rule by calling Set-CsVoiceNormalizationRule.




Determines whether normalization rules will be applied differently based on whether a call was made from Communicator or from an off-hook device (a phone). If True, the prefix in the ExternalAccessPrefix parameter will be applied to calls outside the organization.

Default: False




The state or province served by this dial plan. This property is used for conferencing; it is not needed for Enterprise Voice.




Suppresses any confirmation prompts before making changes.




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

Detailed Description

This cmdlet creates a new dial plan (also known as a location profile). Dial plans provide information required to enable Enterprise Voice users to make telephone calls. Dial plans are also used by the Conferencing Attendant application for dial-in conferencing. A dial plan determines such things as which normalization rules are applied and whether a prefix must be dialed for external calls.

Available scopes: Global, Site, Service, Per-User. The Service scope is restricted to Registrar and PSTN Gateway services.

Return Types

This cmdlet creates an object of type Microsoft.Rtc.Management.WritableConfig.Policy.Voice.LocationProfile.


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

Copy Code
New-CsDialPlan -Identity RedmondDialPlan

The command shown in Example 1 creates a new dial plan with the Identity Redmond. (The absence of a scope in the Identity value indicates that this is a per-user policy. Dial plans created at the per-user scope can be directly assigned to users and groups.) All other properties of the dial plan will be assigned default values.

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

Copy Code
New-CsDialPlan -Identity site:Redmond -SimpleName RedmondSiteDialPlan
Set-CsVoiceNormalizationRule -Identity "site:Redmond/Prefix All" -Pattern "^9(\d*){1,5}$" -Translation "+1206$1"

The commands shown in Example 2 create a new dial plan with the Identity site:Redmond (meaning the dial plan applies to all users on the Redmond site who do not have a per-user dial plan assigned to them) and the SimpleName RedmondSiteDialPlan. The next line in the example then modifies the default normalization rule associated with that plan. The default normalization rule for a dial plan is created mostly as a placeholder--the values are of limited use. So after calling the New-CsDialPlan cmdlet to create a new dial plan, you should call Set-CsVoiceNormalizationRule to modify that default rule to something that is functional for your organization. That’s exactly what line 2 of this example does: it calls Set-CsVoiceNormalizationRule and modifies the Pattern and Translation properties of the rule. No further steps need to be taken to modify the dial plan; the changes to the normalization rule are automatically applied to the dial plan with the identity matching that of the normalization rule. (The site:Redmond portion of the Identity matches the dial plan Identity; the Prefix All is the name of the normalization rule. Multiple normalization rules can be applied to one dial plan, so each normalization rule needs a unique name within a given scope.)

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

Copy Code
New-CsDialPlan -Identity RedmondDialPlan -Description "Dial plan for Redmond users"

The command shown in Example 3 creates a new dial plan with the Identity RedmondDialPlan and specifies a Description to explain what the dial plan is for. (Dial plans created at the per-user scope can be directly assigned to users and groups.) The default values will be assigned for all other parameters.