Test-CsLocationPolicy
Topic Last Modified: 2012-03-26
Runs a test to determine the location policy that will be used based on the criteria specified in the parameter values. The location policy contains the settings that will determine whether and how Enhanced 9-1-1 (E9-1-1) will be applied. E9-1-1 enables those who answer 911 emergency calls to determine the caller’s geographic location.
Syntax
Test-CsLocationPolicy -TargetFqdn <String> [-Force <SwitchParameter>] [-OutVerboseVariable <String>] [-RegistrarPort <Nullable>] [-Subnet <String>] [-UserSipAddress <String>]
Test-CsLocationPolicy [-TargetFqdn <String>] -UserCredential <PSCredential> -UserSipAddress <String> [-Force <SwitchParameter>] [-OutVerboseVariable <String>] [-RegistrarPort <Nullable>] [-Subnet <String>]
Detailed Description
The location policy is used to apply settings that relate to E9-1-1 functionality and client location. The location policy determines whether a user is enabled for E9-1-1, and if so what the behavior is of an emergency call. For example, you can use the location policy to define what number constitutes an emergency call (911 in the United States), whether corporate security should be automatically notified, and how the call should be routed. This cmdlet returns information about the location policy that will be used when calls are made from a particular client on a specific pool, subnet, switch, or wireless access point.
If a user is not specified in the call to this cmdlet, the currently configured user will be tested. To find the currently configured user, call Get-CsHealthMonitoringConfiguration. To set the configured user, call Set-CsHealthMonitoringConfiguration.
If a location policy was found for the user or subnet, the test will succeed. Information returned by default includes the name of the location policy (if a per-user policy is assigned) and whether the user or subnet is enabled for E9-1-1. Include the Windows PowerShell common parameter Verbose to retrieve additional information about the test.
You can test location policies on users or on network subnets. If you run the test against a subnet (by specifying a value for the Subnet parameter), the cmdlet will attempt to resolve the location policy for that subnet. If no location policy is assigned to the subnet, the location policy for the configured user will be retrieved. If the subnet policy is retrieved successfully, the output will include a LocationPolicyTagID value beginning with subnet-tagid. If a location policy for the subnet was not found, the LocationPolicyTagID will begin with user-tagid.
Who can run this cmdlet: By default, members of the following groups are authorized to run the Test-CsLocationPolicy cmdlet locally: RTCUniversalServerAdmins. To return a list of all the role-based access control (RBAC) roles this cmdlet has been assigned to (including any custom RBAC roles you have created yourself), run the following command from the Windows PowerShell prompt:
Get-CsAdminRole | Where-Object {$_.Cmdlets –match "Test-CsLocationPolicy"}
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
TargetFqdn |
Required |
String |
The fully qualified domain name (FQDN) of the pool on which the specified user or subnet is homed. (If no user is specified, the preconfigured or current user will be assumed.) |
OutVerboseVariable |
Optional |
String |
When present, detailed output from running the cmdlet will be stored in the specified variable. For example, to store output in a variable named $TestOutput use the following syntax: -OutVerboseVariable TestOutput Do not prepend a $ character when specifying the variable name. |
RegistrarPort |
Optional |
Integer |
The port number of the Registrar service. |
Subnet |
Optional |
String |
The ID (the IP address) of the network subnet for which you want to test the location policy. |
UserCredential |
Optional |
PS credential object |
An object containing the user ID and password of the user account where the location policy is being tested. A credential object can be retrieved by calling the Windows PowerShell cmdlet Get-Credential, filling in the appropriate information, and saving the output to a variable. |
UserSipAddress |
Optional |
SIP address |
The SIP address of the user whose location policy you want to test. This must be in the format sip:<user id>, for example, sip:kenmyer@litwareinc.com. |
Force |
Optional |
SwitchParameter |
Suppresses any confirmation prompts that would otherwise be displayed before making changes. |
Input Types
None.
Return Types
Test-CsLocationPolicy returns an instance of the Microsoft.Rtc.SyntheticTransactions.TaskOutput object.
Example
-------------------------- Example 1 --------------------------
Test-CsLocationPolicy -TargetFqdn atl-cs-001.litwareinc.com
This example determines the location policy of the current user (or currently configured user). The TargetFqdn is required.
-------------------------- Example 2 --------------------------
$cred = Get-Credential "litwareinc\kenmyer"
Test-CsLocationPolicy -TargetFqdn atl-cs-001.litwareinc.com -UserCredential $cred -UserSipAddress "sip:kenmyer@litwareinc.com"
The first line in Example 2 is a call to the Windows PowerShell Get-Credential cmdlet. This cmdlet will retrieve user credentials and return them as a secure object. The only parameter supplied to this cmdlet is the user ID. Running this cmdlet will open a dialog box that is prepopulated with the user ID supplied and has a text box that allows you to type in the user password. These user credentials are saved to the variable $cred.
Line 2 calls the Test-CsLocationPolicy cmdlet. Just like in Example 1, we supply the target FQDN. However, in this example rather than using the preconfigured user, we’re going to run the test against the user with the SIP address kenmyer@litwareinc.com. We pass that value (with the sip: prefix) to the UserSipAddress parameter, and the credentials for that user (stored in the $cred variable) to the UserCredential parameter.
-------------------------- Example 3 --------------------------
Test-CsLocationPolicy -TargetFqdn atl-cs-001.litwareinc.com -UserSipAddress "sip:kenmyer@litwareinc.com"
This example is similar to Example 2, but without the user credentials specified. When Test-CsLocationPolicy is called without specifying user credentials, the server certificate on the computer where this cmdlet is being run is used to authenticate and discover the user’s location policy. If the computer does not have a server certificate, you must specify credentials as shown in Example 2. To find out whether there is a server certificate on the computer, call the Get-CsCertificate cmdlet.
-------------------------- Example 4 --------------------------
Test-CsLocationPolicy -TargetFqdn atl-cs-001.litwareinc.com -Subnet 172.15.11.0
This example determines the location policy of the subnet with the subnet ID 172.15.11.0. If the subnet is not associated with a location policy, the location policy for the currently configured user will be retrieved.
Note: A location policy is set on a subnet by setting the LocationPolicy parameter of the Set-CsNetworkSite cmdlet to the location policy ID, and then setting the NetworkSiteId parameter of the Set-CsNetworkSubnet cmdlet to the ID of that site. For example:
Set-CsNetworkSite Portland –LocationPolicy Reno
Set-CsNetworkSubnet 175.15.11.0 –NetworkSiteID Portland