Registering Cisco Unity Express Endpoints to Cisco Unified Messaging Gateway

This section describes Cisco Unity Express endpoints, covering principally the new commands in Cisco Unity Express 3.1 to enable endpoints of this type to autoregister with Cisco Unified Messaging Gateway (UMG).

Endpoints running Cisco Unity Express 3.0 or earlier do not support autoregistration. They must be manually configured on Cisco UMG.

The section contains the following topics:

Overview of the Autoregistration Process

The purpose of autoregistration is for Cisco UMG to automatically “discover” a legitimate Cisco Unity Express 3.1 endpoint.

note.gif

Noteblank.gif Currently, the only type of endpoint that can autoregister is Cisco Unity Express 3.1. In the current section, the term ‘endpoint’ refers exclusively to that type of endpoint, unless otherwise specified.

A messaging gateway discovers whether an endpoint is legitimate by attempting to validate the shared secret information in the autoregistration message sent by the endpoint. Successful validation ensures that VPIM messages can only be exchanged between trusted peers.

The autoregistration process starts after the endpoint boots up. An appropriately configured endpoint is enabled to autoregister and it has the following information:

  • The location-id and IP address or domain name of its primary (and where applicable, its secondary) messaging gateway
  • Registration ID and password that the messaging gateways will be expecting.

–blank.gif The instructions for configuring this ID and password on Cisco UMG are given in the Cisco UMG 1.0 CLI Administrator Guide.

–blank.gif The instructions for configuring this ID and password on Cisco Unity Express 3.1 are given below, in Configuring Autoregistration with Cisco UMG.

Beginning the process, the endpoint sends registration requests to both the primary Cisco UMG and the secondary messaging gateway in that order, if a secondary is configured. In the registration message is information about itself, such as its own location ID, broadcast ID, and so on. If the primary messaging gateway encounters configuration problems during registration (for example, a missing location-id), the process will fail, and the endpoint will not try to register with the secondary messaging gateway. If the problems are of a different nature (for example, connectivity problems) the endpoint will go ahead and try to register with the secondary messaging gateway.

When the endpoint autoregisters, the messaging gateway adds the endpoint to a trusted endpoints table and the endpoint is then allowed to send and receive VPIM messages to and from the messaging gateway with which it has registered, as well as to retrieve remote user information.

Automatic directory information exchange takes place a couple of minutes after registration, thereby enabling the messaging gateway to learn about the endpoint’s properties.

Endpoints of the types Cisco Unity Express 3.0 or earlier, Cisco Unity, and Avaya Interchange do not support autoregistration, so they must be individually provisioned from messaging gateways. Instructions for doing this are given in the Cisco UMG 1.0 CLI Adminstrator Guide. An endpoint running Cisco Unity Express 3.1 that is not enabled to autoregister will be treated the same as these other types of endpoint.

Configuring Autoregistration with Cisco UMG

An endpoint running Cisco Unity Express 3.1 or later can autoregister with Cisco Unified Messaging Gateway. This means that when the endpoint comes online, it seeks out its messaging gateways (both primary and secondary, if configured) and registers itself. The alternative - manual provisioning (as opposed to autoregistration) - entails configuring all relevant details of each endpoint on its messaging gateway. This is the only option available to endpoints not running Cisco Unity Express 3.1.

After the messaging gateway authorizes the endpoint, it exchanges directories with its peers so that the whole system becomes aware that this endpoint is now online. Once you have enabled autoregistration, any time either the endpoint or the messaging gateway goes offline, the endpoint will re-register automatically as soon as both come back online.

Before enabling autoregistration, you must first specify the primary and then the secondary messaging gateway access information. Only after this do you enable autoregistration. Issuing these commands causes the profile(s) for the messaging gateways to be stored in the running configuration on Cisco Unity Express 3.1.

note.gif

Noteblank.gif The endpoint cannot autoregister until you issue the messaging-gateway registration command.

caut.gif
Caution blank.gif You must copy the configurations to the startup-config to make them persistent.

Save the configuration to the startup config by using the write command.

SUMMARY STEPS

1.blank.gif config t

2.blank.gif messaging-gateway registration

3.blank.gif messaging-gateway primary location-id umg-ip-addr [ port umg-port ]

4.blank.gif username umg-reg-id password encryption-level umg-passwd

5.blank.gif (Optional) retry-interval retry-interval ]

6.blank.gif end

7.blank.gif (Optional) messaging-gateway secondary location-id umg-ip-addr [ port umg-port ]

8.blank.gif (Optional) username umg-reg-id password encryption-level umg-password

9.blank.gif (Optional) retry-interval retry-interval ]

10.blank.gif end

11.blank.gif end

12.blank.gif show messaging-gateway

DETAILED STEPS

Command or Action
Purpose

Step 1
config t
 

se-10-0-0-0# config t

Enters configuration mode.

Step 2

messaging-gateway registration

 

se-10-0-0-0(config)# messaging-gateway registration

Causes the endpoint (Cisco Unity Express) to send a registration message to its primary and, if applicable, to its secondary messaging gateway, unless registration with the primary fails due to a configuration error.

Step 3

messaging-gateway primary location-id umg-ip-addr
[ port umg-port ]

 

se-10-0-0-0(config)# messaging-gateway primary 100 192.0.2.0 port 8080

Enters gateway configuration mode and specifies the following information for the primary messaging gateway:

  • location-id-- the location-id of the primary messaging gateway
  • umg-ip-addr-- the IP address or domain name of the primary messaging gateway
  • (optional) port --port the primary messaging gateway will be listening on. The default port is 80.

The primary Cisco UMG must be configured before the secondary. Otherwise, you will get the error message “Primary messaging gateway needs to be configured first.”

Step 4

username umg-reg-id password encryption-level umg-password

 

se-10-0-0-0(config-gateway)# username cue31 password text herein

(Optional) Specifies the username and password required to authorize registration with the message gateway.

  • umg-reg-id-- the registration ID the endpoint will use to register with the messaging gateway.

    Note that it is not necessarily the same as the location-id, because multiple endpoints may be assigned the same umg-reg-id.

You can give either an encrypted password or non-encrypted password: encrypted and text tokens need to be used.

  • encryption-level -- The two acceptable values for this variable are

–blank.gif text

–blank.gif encrypted

  • umg-password --the password for registration with a messaging gateway is an alphanumeric string up to x in length.

Step 5

retry-interval retry-interval

 

se-10-0-0-0(config-gateway)# retry-interval 2

(Optional) The retry-interval is the delay before the endpoint attempts to re-register with the messaging gateway. The value is expressed in minutes. The default is 5 minutes.

Step 6

end

 

se-10-0-0-0(config-gateway)# end

Exits gateway configuration mode and enters configuration mode.

Step 7

messaging-gateway secondary location-id umg-ip-addr [ port umg-port ]

 

se-10-0-0-0(config)# messaging-gateway secondary 200 192.0.2.1 port 8080

(Optional) Enters gateway configuration mode and specifies the following information for the secondary messaging gateway:

  • location-id-- the location-id of the secondary messaging gateway
  • umg-ip-addr-- the IP address or domain name of the secondary messaging gateway, and
  • (optional) port --port the secondary messaging gateway will be listening on. The default port is 80.

The secondary Cisco UMG must be configured after the primary. Otherwise, you will get the error message “Primary messaging gateway needs to be configured first.”

Step 8

username umg-reg-id password encryption-level umg-password

 

se-10-0-0-0(config-gateway)# username cue31 password text herein

(Optional) Specifies the username and password required to authorize registration with the message gateway.

  • umg-reg-id-- the registration ID the endpoint will use to register with the messaging gateway.

    Note that it is not necessarily the same as the location-id, because multiple endpoints may be assigned the same umg-reg-id.

You can give either an encrypted password or non-encrypted password: encrypted and text tokens need to be used.

  • encryption-level -- The two acceptable values for this variable are

–blank.gif text

–blank.gif encrypted

  • umg-password --the password for registration with a messaging gateway is an alphanumeric string up to x in length.

Step 9

retry-interval retry-interval

 

se-10-0-0-0(config-gateway)# retry-interval 2

(Optional) The retry-interval is the delay before the endpoint attempts to re-register with the messaging gateway. The value is expressed in minutes. The default is 5 minutes.

Step 10

end

 

se-10-0-0-0(config-gateway)# end

Exits gateway configuration mode and enters config mode.

Step 11

messaging-gateway registration

 

se-10-0-0-0(config)# messaging-gateway registration

Causes the endpoint to send a registration message to its primary and, if applicable, to its secondary messaging gateway - unless registration with the primary fails due to a configuration error.

Step 12

end

 

se-10-0-0-0(config)# end

Exits config mode and enters EXEC mode.

Step 13

show messaging-gateway

 

se-10-0-0-0# show messaging-gateway

(Optional) Displays the details associated with the registration of the messaging gateway, successful or otherwise. For more information, see the “Verifying the Registration Status of a Cisco Unity Express Endpoint” section.

Step 14

write memory

 

se-10-0-0-0# write memory

Copies the running-config to the startup-config and thereby ensures that the foregoing autoregistration configurations are not lost if the endpoint goes down.

Example

The following commands on a Cisco Unity Express 3.1 endpoint set it up to autoregister with Cisco UMG, and then enable autoregistration and finally write the configuration to startup-config.

se-10-0-0-0# config t
se-10-0-0-0(config)# messaging-gateway primary 100 192.0.2.0 port 8080
se-10-0-0-0(config-gateway)# username cue31 password text herein
se-10-0-0-0(config-gateway)# retry-interval 2
se-10-0-0-0(config-gateway)# end
se-10-0-0-0(config)# messaging-gateway secondary 200 192.0.2.1 port 8080
se-10-0-0-0(config-gateway)# username cue31 password text herein
se-10-0-0-0(config-gateway)# retry-interval 2
se-10-0-0-0(config-gateway)# end
se-10-0-0-0(config)# messaging-gateway registration
se-10-0-0-0(config)# end
se-10-0-0-0# write memory

Manually Registering a Cisco Unity Express Endpoint

If you want to add a Cisco Unity Express endpoint to your Cisco UMG system, and it is either

  • running Cisco Unity Express 3.0 or earlier, or
  • you want to avoid autoregistration activity with an endpoint running Cisco Unity Express 3.1,

you must manually provision it from Cisco UMG. First configure the endpoint, then provision it on Cisco UMG.

note.gif

Noteblank.gif You need to perform these steps only if the endpoint has never undergone initial configuration - if the endpoint is already in operation, you will already have done all this. In that case, there is nothing left to do on the endpoint.

SUMMARY STEPS

1.blank.gif config t

2.blank.gif network location-id number

3.blank.gif (Optional) name location-name

4.blank.gif (Optional) abbreviation name

5.blank.gif email domain domain-name

6.blank.gif voicemail phone-prefix digit string

7.blank.gif (Optional) voicemail extension-length number [min number | max number]

8.blank.gif (Optional) voicemail vpim-encoding {dynamic | G711ulaw | G726}

9.blank.gif (Optional) voicemail spoken-name

10.blank.gif end

Repeat Steps 2 through 10 for each remote location.

11.blank.gif network local location-id number

12.blank.gif end

13.blank.gif show network locations configured

14.blank.gif show network detail location-id number

15.blank.gif show network detail local

16.blank.gif show network queues

DETAILED STEPS

 

Command or Action
Purpose

Step 1

config t

 

se-10-0-0-0# config t

Enters configuration mode.

Step 2

network location-id number

 

se-10-0-0-0(config)# network location-id 9

Enters location configuration mode to allow you to add or modify a location.

  • number—A unique numeric ID assigned to the location. This number is used to identify the location and is entered when a subscriber performs addressing functions in the TUI. The maximum length of the number is 7 digits. Cisco Unity Express supports up to 500 locations on a single system.
  • To delete a location, use the no form of this command.

Step 3

name location-name

 

se-10-0-0-0(config-location)# name “San Jose”

(Optional) Descriptive name used to identify the location. Enclose the name in double quotes if spaces are used.

  • To delete a location name description, use the no form of this command.

Step 4

abbreviation name

 

se-10-0-0-0(config-location)# abbreviation sjcal

(Optional) Creates an alphanumeric abbreviation for the location that is spoken to a subscriber when the subscriber performs addressing functions in the TUI. You cannot enter more than 5 characters.

  • To delete an abbreviation, use the no form of this command.

Step 5

email domain domain-name

 

se-10-0-0-0(config-location)# email domain mycompany.com

Configures the e-mail domain name or IP address for the location. The domain name is added when sending a VPIM message to the remote location (for example, “4843000@mycompany.com”). If you do not configure a domain name or IP address, the Cisco Unity Express system at this location cannot receive network messages.

  • To remove the e-mail domain name or IP address and disable networking, use the no form of this command.
caut.gif
Caution If you remove the e-mail domain for a network location, the system automatically disables networking from the Cisco Unity Express module to that location.
If you remove the e-mail domain for the local location, then networking on that Cisco Unity Express module is disabled.
To reenable a location, assign it a valid e-mail domain.

Step 6

voicemail phone-prefix digit-string

 

se-10-0-0-0(config-location)# voicemail phone-prefix 484

(Optional) Configures the phone number prefix that is added to an extension to create a VPIM address for a subscriber at the location. A prefix is required only if an e-mail domain services multiple locations and extensions between the locations are not unique. Valid values: 1 to 15 digits. Default value: empty.

  • To delete a phone prefix, use the no form of this command.

Step 7

voicemail extension-length {number | min number max number}

 

se-10-0-0-0(config-location)# voicemail extension-length 8

 

se-10-0-0-0(config-location)# voicemail extension-length min 5 max 9

(Optional) Configures the voice mail extension length for the location.

  • number—Configures the number of digits contained in extensions at the location.
  • max number—Sets the minimum number of digits for extensions. Default value: 2.
  • min number—Sets the maximum number of digits for extensions. Default value: 15.
  • To remove the configuration for the number of digits for extensions, use the no form of this command.

Step 8

voicemail vpim-encoding {dynamic | G711ulaw | G726}

 

se-10-0-0-0(config-location)# voicemail vpim-encoding G711ulaw

(Optional) Configures the encoding method used to transfer voice-mail messages to this location.

  • dynamic—Cisco Unity Express negotiates with the location to determine the encoding method
  • G711ulaw—Cisco Unity Express always sends messages as G711 mu-law.wav files. Set this only if the receiving system supports G711 mu-law encoding (such as Cisco Unity).
  • G726—Cisco Unity Express always sends messages as G726 (32K ADPCM). Use for low-bandwidth connections or when the system to which Cisco Unity Express is connecting does not support G711 u-law.
  • Default value: dynamic.
  • To return to the default value for encoding, use the no or default form of this command.

Step 9

voicemail spoken-name

 

se-10-0-0-0(config-location)# voicemail spoken-name

(Optional) Enables sending the spoken name of the voice-mail originator as part of the message. If the spoken name is sent, it is played as the first part of the received message. Default: enabled.

  • To disable sending the spoken name, use the no form of this command.

Step 10

end

 

se-10-0-0-0(config-location)# end

Exits location configuration mode.

Step 11

network local location-id number

 

se-10-0-0-0(config)# network local location-id 1

Enables networking for the local Cisco Unity Express system identified by the location-id number.

  • To delete the local location, use the no form of this command.
caut.gif
Caution If you delete the local network location and then save your configuration, when you reload Cisco Unity Express, the local network location will remain disabled. After Cisco Unity Express restarts, reenter the network local location-id command to reenable networking at this location.

Step 12

exit

 

se-10-0-0-0(config)# exit

Exits configuration mode.

Step 13

show network locations configured

 

se-10-0-0-0# show network locations configured

(Optional) Displays the location-id, name, abbreviation, and domain name for each configured Cisco Unity Express location.

Step 14

show network detail location-id number

 

se-10-0-0-0# show network detail location-id 9

(Optional) Displays network information for the specified location-id, including the number of messages sent and received.

Step 15

show network detail local

 

se-10-0-0-0# show network detail local

(Optional) Displays network information for the local Cisco Unity Express location, including the number of messages sent and received.

Step 16

show network queues

 

se-10-0-0-0# show network queues

(Optional) Displays information about messages in the outgoing queue that are to be sent from this Cisco Unity Express system. The queue information contains three displays: one for urgent job queue information, one for normal job queue information, and one for running job information.

Examples

The following examples illustrate the output from the show network commands on company Mycompany’s call control system in San Jose with remote voice-mail provided by six remote Cisco Unity Express sites.

se-10-0-0-0# show network locations
 
ID NAME ABBREV DOMAIN
101 'San Jose' SJC sjc.mycompany.com
102 'Dallas/Fort Worth' DFW dfw.mycompany.com
201 'Los Angeles' LAX lax.mycompany.com
202 'Canada' CAN can.mycompany.com
301 'Chicago' CHI chi.mycompany.com
302 'New York' NYC nyc.mycompany.com
401 'Bangalore' BAN bang.mycompany.com
 
se-10-0-0-0# show network detail location-id 102
 
Name: Dallas/Fort Worth
Abbreviation: DFW
Email domain: dfw.mycompany.com
Minimum extension length: 2
Maximum extension length: 15
Phone prefix:
VPIM encoding: G726
Send spoken name: enabled
Sent msg count: 10
Received msg count: 110
 
se-10-0-0-0# show network detail local
 
location-id: 101
Name: San Jose
Abbreviation: SJC
Email domain: sjc.mycompany.com
Minimum extension length: 2
Maximum extension length: 15
Phone prefix:
VPIM encoding: dynamic
Send spoken name: enabled
 

The following example illustrates output from the show network queues command. The output includes the following fields:

  • ID—Job ID.
  • Retry—Number of times that Cisco Unity Express has tried to send this job to the remote location.
  • Time—Time when the job will be resent.
se-10-0-0-0# show network queues
 
Running Job Queue
=================
 
ID TYPE TIME RETRY SENDER RECIPIENT
107 VPIM 06:13:26 20 jennifer 1001@sjc.mycompany.com
106 VPIM 06:28:25 20 jennifer 1001@sjc.mycompany.com
 
Urgent Job Queue
=================
 
ID TYPE TIME RETRY SENDER RECIPIENT
123 VPIM 16:33:39 1 andy 9003@lax.mycompany.com
 
Normal Job Queue
=================
 
ID TYPE TIME RETRY SENDER RECIPIENT
122 VPIM 16:33:23 1 andy 9001@lax.mycompany.com
124 VPIM 16:34:28 1 andy 9003@lax.mycompany.com
125 VPIM 16:34:57 1 andy 9002@lax.mycompany.com
126 VPIM 16:35:43 1 andy 9004@lax.mycompany.com
 

After performing on the endpoint the steps just listed, on the Cisco UMG that is to be the endpoint’s primary messaging gateway, manually provision the endpoint by following the instructions given in the Cisco UMG 1.0 CLI Adminstrator Guide.

Register the endpoint by issuing the Cisco UMG command location-id cue enabled (fully described in the Cisco UMG 1.0 CLI Adminstrator Guide) on the endpoint’s primary messaging gateway.

On that messaging gateway, verify that the endpoint is registered to it by using the command show endpoint local.

Verifying the Registration Status of a Cisco Unity Express Endpoint

You can verify whether the current Cisco Unity Express 3.1 or later version endpoint is registered with a messaging gateway, and check all the details associated with the registration - successful or otherwise - by using the show messaging-gateway command in Cisco Unity Express EXEC mode.

You can see which Cisco UMGs you have configured as its primary and secondary messaging gateways, with their respective port numbers. Indications in the status column show whether or not the endpoint has registered with the messaging gateway successfully.

 

Table 23-1 show messaging-gateway Output

AutoRegister to messaging gateway(s)

Enabled / disabled

 

 

Remote directory lookup

Enabled / disabled

with / without TUI prompt

 

Primary/secondary messaging gateway

IP address (port number)

 

 

 

Status

Registered / Not Registered

If registered, timestamp of initial registration confirmation; if not registered, reason is given as a code (see Table 23-2 )

 

Default route

Enabled/ disabled

 

 

Location-id

location-id of the messaging gateway

 

 

Reg-id

Registration username the Cisco UMG expects from endpoint

 

 

Reg-password

(Not displayed)

Registration password the Cisco UMG expects from endpoint. It is never displayed.

 
Retry-interval

Delay in minutes before the endpoint attempts to register again. Default is 5 minutes.

Not displayed if not set.

If the endpoint has registered successfully, you will see the date and time of the initial registration in the status column. You can also check the configuration for a default routing destination for a message to a voicemail address that can be resolved by neither Cisco Unity Express nor Cisco UMG. To illustrate: if you give a phone number that cannot be found in a Cisco Unity Express local search or in a Cisco UMG remote lookup, the message will be forwarded to that default route destination.

If the endpoint has not registered successfully, the reason for the failure will be displayed in the status column:

Table 23-2 show messaging-gateway: Status Codes
Code
Meaning

Registered

 

Not registered

Autoregistration is not enabled

Not configured

 

Not registered (general error)

Autoregistration failed due to an error other than those specified in this table.

Not registered (connection timeout)

Connection timed out

Not registered (authentication failed)

Authentication failed

Not registered (link is down)

Link is down

Not registered (location is forbidden)

The Cisco Unity Express endpoint with that location-id has been blocked by Cisco UMG and is thus is not allowed to register (for instructions on how to prevent an endpoint from registering, see the Cisco UMG 1.0 CLI Adminstrator Guide.

Not Registered (duplicated location)

The Cisco Unity Express location-id is not globally unique: there is another entity in the system with the same location-id.

Not Registered (invalid configuration)

General configuration error such as the secondary messaging gateway location ID not being configured on the primary messaging gateway.

Not Registered (manually de-registered)

An intermediate state to indicate manually triggered re-registration, for example, the messaging gateway’s access information being updated.

The following command on a Cisco Unity Express 3.1 or later version endpoint displays its registration status:

se-10-0-0-0# show messaging-gateway
Messaging gateways :
 
AutoRegister to messaging gateway(s) : Enabled
Remote directory lookup : Enabled (without TUI prompt)
 
Primary messaging gateway :
172.18.12.28 (8080)
Status : Registered (Sun Jun 10 20:35:43 GMT 2007)
Default route : Disabled
Location-id : 50000
Reg-id : umg
Reg-password : (Not displayed)
Retry-interval : 5 minute(s)
 
Secondary messaging gateway :
Status : Not Configured

Enabling or Disabling Remote Lookup, With or Without TUI Confirmation

Enabling Remote Directory Lookup Without TUI Prompt

When you enable autoregistration by issuing the messaging-gateway registration command on a Cisco Unity Express 3.1 endpoint, you also enable the endpoint to do remote lookup automatically. This includes a short prompt informing subscribers that the lookup may take some time.

Enabling Remote Directory Lookup With TUI Prompt

Enabling the remote directory lookup feature does not also enable the directory lookup confirmation in the TUI flow feature, in which Cisco Unity Express 3.1 gives subscribers the option to do remote lookup if there is no local match. To enable TUI directory lookup confirmation, use the config-mode command messaging-gateway directory lookup tui-prompt.

Disabling Remote Directory Lookup

To have no remote lookup at all, disable it by issuing the no messaging-gateway directory lookup command.

note.gif

Noteblank.gif Disabling the remote directory lookup feature also disables directory lookup confirmation in the TUI flow, and conversely, enabling directory lookup confirmation in the TUI flow will also enable remote directory lookup.

Viewing Status

To view the status of these features, use the show messaging-gateway command, which displays the following output:

Remote directory lookup status:

  • No--remote directory lookup is disabled
  • Yes--remote directory lookup is enabled

–blank.gif Enabled with TUI-prompt--TUI confirmation prompt is enabled

–blank.gif Enabled without TUI-prompt--TUI confirmation prompt is disabled.

Viewing Cached and/or Configured Network Locations

To view a list of all cached remote location entries on Cisco Unity Express 3.1, use the EXEC-mode show network locations cached command.

To list all configured remote location entries on Cisco Unity Express 3.1, use the EXEC-mode show network locations configured command. This command replaces the old show network locations command.

Refreshing Locations

To manually refresh a cached location entry on Cisco Unity Express 3.1, use the network location cache refresh id command in EXEC-mode. This command will not generate any response if it is performed successfully. Otherwise, an error message appears.

Setting the Expiration for Cached Locations

To set the expiration time for a cached location on Cisco Unity Express 3.1, use the network location cache expiry int command in config-mode. The int value stands for number of days. By default, this value is set to 4. The no command will set the value back to its default value. The value is persisted by means of the nvgen method. It is not stored in the database.

Overloading a NAT Device: the Consequences for Endpoints

One endpoint can be configured to get to its primary messaging gateway with complete connectivity if :

  • Two Cisco Unity Express endpoints are behind a NAT device that has only one IP address to assign --an overload situation--
  • Those endpoints have two different messaging gateways configured as primary messaging gateways,
note.gif

Noteblank.gif The other endpoint can only do HTTP-related activities (assuming proper configuration) and not the SMTP activities.